Start a headless Google sign-in. Call this FIRST if you don't have an API token yet. Returns a user_code and verification_url for the user to visit, plus a device_code to use with poll_device_auth. No Bearer token required.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description takes on full responsibility. It discloses that no Bearer token is required and details the exact returned values (user_code, verification_url, device_code), offering enough behavioral transparency for an agent. It stops short of 5 by omitting any error/expiration details, but these are not critical for this simple auth step.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place: purpose, trigger condition, and output usage. It is front-loaded with the action and contains no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 0-parameter tool with no output schema, the description fully covers what it does, when to call it, and how to proceed with the returned codes. The explicit link to poll_device_auth ensures the agent understands the overall flow, making this complete in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so a baseline of 4 is appropriate. The description adds no parameter information, but none is needed since the schema is empty and the description clarifies the context in which the tool is invoked.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function ('Start a headless Google sign-in.') and differentiates it from siblings by explicitly referencing poll_device_auth as the next step, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance ('Call this FIRST if you don't have an API token yet') and directs the use of the returned device_code with poll_device_auth, giving clear context relative to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool has a distinct role: document CRUD (create, get, update, archive), listing/searching, annotation create/list, and two auth helper tools. There is no overlap or ambiguity between them.
All tools follow a consistent verb_noun pattern with snake_case (e.g., create_document, list_annotations, request_device_auth). The naming is uniform and predictable across both document and auth tools.
With 10 tools, the server is well-scoped for document management plus required auth flow. It covers the essential operations without being bloated or too thin.
Core document operations are covered (create, read, update, archive, list, search), but there is no hard delete or unarchive, and annotations only support create/list (no update/delete). Additionally, there is no explicit tool for sharing documents despite the mention of shared docs.
