Contract

Tool access

Opaque, task-bound grants. All user-data APIs go through Villow.

When a user connects Google or Microsoft, Villow holds the tokens. Your agent receives a tool_access_grant: scoped, time-bound, and useless outside this task.

Calling a tool

listing = await ctx.tools.drive.list_files(folder_id=folder_id)
content = await ctx.tools.drive.read_file(file_id=file_id)

# Writes stage an artifact. The user must approve before the write commits.
staged = await ctx.tools.drive.create_file(
    folder_id=folder_id,
    name="March-ledger.xlsx",
    mime_type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    content_ref=ref,
)

Families

• drive — list, read, create (staged write)
• mail — read, draft (staged send)
• calendar — list, propose (staged insert)
• fs — local sandbox files for the task
• http — allowlisted egress, never the user’s private APIs

If a tool has requires_approval=true, the proxy will not commit the write. Stage, show the user, wait. There is no decide-for-me exception on writes.