Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial context beyond the annotations: it writes the registry, launches Google consent in the browser, needs no file edit or restart, but services newly enabled only register at the next restart. The destructiveHint=true/write profile is consistent and further explained by 'writes the registry'.

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?

Front-loads the core action and keeps everything in a tight, dense paragraph; each clause (modes, side effects, restart caveat, credential prerequisite) carries information. Parenthetical asides add minor length but not waste.

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 an OAuth-flow tool with no output schema, it covers the necessary operational context: two invocation modes, side effects, restart timing, and credential prerequisites. Nothing an agent needs to call it correctly is missing.

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?

Schema description coverage is 100%, so the schema already documents all six parameters, including the alias/account aliasing. The description adds only the alias+email pairing rule and the bundles/allBundles/admin options, which is marginal over structured data, so the baseline 3 applies.

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?

States a specific verb+resource ('Add a new Google account') and immediately distinguishes itself from siblings like account_list and account_reauth by describing the add/registry-write behavior. An agent can tell what this does without opening the schema.

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?

Gives explicit invocation conditions: pass alias+email to add directly, or pass nothing for the interactive form on elicitation-capable clients, plus the GOOGLE_CLIENT_ID/SECRET prerequisite ('run the `setup` prompt first'). It does not explicitly contrast against account_reauth, so it falls just short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description goes beyond that by disclosing the possible token states (ok / expired_refreshable / needs_reauth / missing / decrypt_error), which tells an agent what follow-up actions might be warranted, though it omits auth requirements or ordering caveats.

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?

Two sentences with no filler; the returned-field inventory is front-loaded and the verbose option is tucked at the end as the only optional action. Every clause carries information an agent needs.

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?

There is no output schema, so the description carries the return-value burden itself — and it does so by listing the concrete per-account fields and token status values. For a zero-required-parameter, one-optional-parameter read tool, nothing needed to invoke or interpret it is missing.

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?

Schema coverage is 100%, so the baseline is 3, but the description enriches the verbose parameter beyond the schema text: instead of a generic 'full scope report' it specifies 'granted vs configured scopes', clarifying what the richer output actually contains. That is real added meaning over the structured field.

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?

Names a specific verb and resource (list configured Google accounts) and enumerates exactly what each entry contains: alias, email, admin flag, token status, and default marker. An agent can distinguish this from account_add, account_reauth, or account_write_config without opening any schema.

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?

The description implies its usage (enumerate accounts) and gives one conditional instruction — pass verbose: true for the full per-account report — but never states when to prefer this tool over siblings like diagnose or account_reauth, nor any prerequisites. Usage is inferable but not guiding.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare this is a non-read-only, open-world, idempotent operation, so the safety bar is lower. The description adds genuinely useful behavior the annotations cannot express: consent runs in the browser, meaning the call is interactive/blocking. It does not explain the destructiveHint=true flag (e.g. whether existing tokens are invalidated), which is the one notable omission.

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?

Three short sentences, front-loaded with purpose, then the caveat that consent happens in the browser, then the required input. Every sentence carries information and none is wasted.

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?

There is no output schema, so the description must carry the interaction burden, and it does flag the browser consent step. However, for a tool flagged destructive with no explanation, it leaves the agent guessing about token invalidation, failure modes, and what state the account is left in if consent is abandoned.

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?

Schema description coverage is 100% and both params are self-documented, so baseline is 3. The schema exposes two duplicate parameters (alias and account, the latter documented as 'same as `alias`'), and the description only says 'Pass the account alias' without clarifying the redundancy or which one takes precedence.

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?

States a specific verb and resource ('Re-authenticate an existing Google account') and immediately scopes the purpose with two concrete scenarios (dead refresh token, post-profile-change scope grants). It is clearly distinguishable from account_add and account_write_config in the sibling list, though it never names them explicitly.

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?

Gives the two trigger conditions for choosing this tool ('recover a dead refresh token, or grant scopes after a profile change'), which is strong contextual guidance. It stops short of stating when NOT to use it (e.g. for adding a brand-new account, use account_add) or listing prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With annotations already declaring destructiveHint=true and idempotentHint=true, the description adds genuinely useful context beyond them: it backs up before writing, never clobbers a malformed file, and never inlines secrets. These are safety-relevant traits an agent could not infer from the annotation block alone.

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?

Three dense sentences, front-loaded with the core action and immediately followed by the default-vs-write decision, with the safety caveats last. No filler.

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?

No output schema exists, and the description compensates by describing both return paths (snippet/command vs in-place write) and the non-clobber guarantee. Minor gaps remain around non-file-based clients and what 'detected' means, but the essentials for correct invocation are present.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds behavioral meaning to write:true (in-place write with backup) and to the default mode (snippet only) that goes slightly beyond the terse schema descriptions.

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 states a concrete verb and resource — register this server by producing MCP client config — and names the exact clients (Claude Code / Claude Desktop / Cursor). It cleanly disambiguates from siblings like account_add and account_list, which manage credentials rather than client config files.

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 explicitly frames the two modes: default returns the snippet/command, and write:true writes detected file-based configs in place. It does not explicitly say when not to use it or name a sibling alternative, so it stops short of a full when/when-not rubric.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/idempotentHint true and destructiveHint false, so the safety profile is covered. The description adds genuinely non-structured context: that the tool reveals otherwise-hidden operations and roughly how many ops/areas exist, telling the agent what comes back from the call.

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?

Purpose and the 'call first' instruction are front-loaded in one dense sentence. The op/area enumeration is long and ends in truncated fragments ('+2 more', '+1 areas'), which is mildly awkward but still communicates scope for a catalog tool.

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?

There is no output schema, so the description must convey what the tool yields; it does so at a high level (catalog plus hidden tool names). For a read-only, zero-required-parameter discovery tool this is close to sufficient, with only the exact response shape left implicit.

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 single 'query' parameter is fully documented in the schema (100% coverage) as a filter keyword, so the schema carries the load. The description adds no syntax, matching behavior, or filtering semantics beyond what the schema already states, which is the baseline case.

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?

Names a specific verb and resource ('Discover calendar') and immediately states the mechanism: it lists the catalog and reveals hidden tools. It also enumerates the underlying operations, which distinguishes it cleanly from the parallel gmail_discover, drive_discover, sheets_discover siblings without opening any schema.

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?

Gives explicit ordering guidance ('call first, then call the tool by name'), which is exactly the sequencing an agent needs for a discovery/meta tool. It does not state when not to use it or when a sibling discover tool would be preferable, so it stops short of full routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description usefully adds that this is a discovery/meta step that 'reveals hidden tools' and must be invoked first. However, enumerating 'create, update, delete' as ops alongside a readOnly annotation creates real potential for the agent to mistake this for a mutating call, and the return structure of the catalog is never characterized.

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 core instruction is front-loaded in the first clause, and the workflow ordering follows immediately. The long semicolon-delimited ops enumeration is dense and its value is questionable, but the description is not padded with filler.

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?

With no output schema, the description carries the burden of explaining what discovery returns, and 'lists the catalog and reveals its hidden tools' plus the ops enumeration gives the agent a usable roadmap. It still does not describe the shape of the catalog response or how a 'hidden tool' is addressed by name, leaving a modest gap for a meta-tool.

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?

Schema description coverage is 100% ('query: Filter keyword'), so the schema already documents the single optional parameter. The description never mentions that query filters the catalog listing, so it adds no semantic value beyond the structured field; baseline 3 applies.

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 states a specific action ('lists the catalog and reveals its hidden tools') on a specific resource (contacts), and distinguishes itself from siblings like discover_all and gmail_discover by scoping to the contacts domain. The trailing 'Ops' enumeration is confusing because it lists downstream operations (create/update/delete) rather than what this call does, muddying the otherwise clear purpose.

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?

Explicit sequencing guidance is given: 'call first, then call the tool by name.' That tells the agent exactly when this tool belongs in the workflow and what follows it. It does not name a competing sibling (e.g., discover_all) or state when not to use it, keeping it short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior. The description adds useful output context ('returns copy-pasteable fixes for anything wrong') and the report scope, though it repeats the read-only hint and omits auth prerequisites or rate limits.

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?

Two tightly written sentences: the report contents are front-loaded in a colon list, followed by safety/output note and the call-to-action. No filler or repetition.

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?

With no input parameters and no output schema, the description must carry the return-value burden, and it does: it lists the report sections and says it returns copy-pasteable fixes. Annotations cover safety and idempotency, so an agent has enough to call it correctly.

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 input parameters, so parameter semantics are not applicable; the baseline for 0 params is 4. The description does not need to explain any parameters.

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?

States a specific diagnostic resource (server health report) and enumerates the covered areas (runtime, config, keys, token status, scope grants, API enablement). It does not explicitly name or differentiate from sibling tools, but the diagnostic purpose is clear against the discover/account-management siblings.

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?

Explicitly says 'Call this to diagnose auth/config failures', giving a clear trigger context. It does not list exclusions or alternative tools for related but different diagnostics, so it falls short of full when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/idempotentHint true and destructiveHint false, so the safety profile is covered. The description adds real behavioral context beyond that: this bulk-reveals the curated toolset rather than a single service, and it should be paired with discover_reset, implying a persistent discovery state. It does not explain whether already-discovered tools are duplicated, but the gap is minor given annotation coverage.

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?

Two tight sentences; the action and bulk scope are front-loaded, followed by usage conditions. No filler or restated title.

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?

With no parameters, no output schema, and annotations covering the safety profile, the description carries everything an agent needs: what is revealed, when to prefer it, and the companion reset tool. Nothing material is missing.

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 takes zero parameters, so parameter semantics are trivially satisfied and the baseline is 4. Nothing in the description is needed to clarify inputs.

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?

States a specific verb ('Reveal') and resource ('ALL curated Google tools'), with the scope ('at once, instead of per-service discovery') that separates it from the gmail_discover/drive_discover family. An agent can distinguish it from every sibling without opening a schema.

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?

Explicitly prescribes when to use it ('when starting substantial Google work'), names the alternative it replaces (per-service discovery) and the downstream preference over google_api_call, and pairs it with discover_reset. When-to-use, alternative, and follow-up are all present.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only cover the read-only/idempotent safety profile; the description adds the non-obvious behavior that collapsing does not unload tools permanently — they remain callable by name. That is real context beyond structured fields, though it omits what the call returns or whether it is a no-op when already at default.

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?

Two tight sentences with the action front-loaded and no filler; the payoff (all tools still callable) follows immediately. Minor: neither sentence is wasteful.

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?

With no parameters, no output schema, and annotations already carrying the safety profile, the description supplies enough for correct invocation. A note on idempotent/no-op behavior or confirmation output would close the remaining gap.

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 takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies.

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?

States a concrete verb and effect: collapse the tool surface back to the configured default. It is clearly the inverse of the *_discover / discover_all siblings, though it never names one explicitly to sharpen the contrast.

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?

"Reclaiming context budget after heavy Google work" gives a clear triggering condition for when to call it, and the second sentence sets expectations afterward. It stops short of stating when not to use it or naming an alternative tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds that the tool 'reveals its hidden tools' and must be called first, which is key behavioral context. Auth and rate limits are not covered, but with annotations that is acceptable.

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?

Front-loaded with purpose and sequence in two compact clauses. The trailing 'Ops:' list is long but informative and earns space by enumerating available hidden tools; there is no filler.

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 discovery tool with one optional parameter and no output schema, the description provides the essential call-first workflow and reveals that a catalog and hidden tools are returned. Nothing critical for invocation is missing, though it could clarify what 'Ops' refers to.

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?

Schema coverage is 100% and the sole optional parameter 'query' is documented as 'Filter keyword'. The description does not mention the query parameter or add syntax/format details, so it adds no value beyond the schema. Baseline 3 applies.

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?

States a specific verb and resource ('Discover docs') and describes output: 'lists the catalog and reveals its hidden tools'. The docs domain distinguishes it from sibling discover tools like drive_discover, though no sibling is named explicitly in the text.

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?

Provides explicit sequencing: 'call first, then call the tool by name.' This tells the agent when to use it (first) and what to do next. No when-not or alternative discovery tools are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond that: this is a meta-discovery step that must precede invoking any drive tool, and it signals the breadth of the hidden catalog. It omits return shape/pagination details, but with annotations doing that work a 4 is warranted.

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?

Purpose and call-order are front-loaded, which is good, but the long op enumeration ('search, read, list, upload... delete, trash +26 more; 35 generated ops...') is filler that describes the discovered catalog rather than this tool and risks confusing the agent about scope.

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?

There is no output schema, but the description conceptually explains the return (a catalog of drive tools and op areas) and the required call order, which is the key information an agent needs. The misleading op list is the main residual gap.

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?

Schema description coverage is 100% for the single 'query' filter parameter, so the schema already documents it fully. The description never mentions filtering by keyword, adding no meaning beyond the schema; per the coverage rule, baseline 3 is correct.

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 first clause states a specific verb and resource ('lists the catalog and reveals its hidden tools') and the 'drive' scope distinguishes it from gmail_discover, calendar_discover, and the other domain discover tools. The trailing enumeration of downstream ops (upload, delete, trash) muddies what this tool itself does, keeping it short of a clean 5.

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?

'call first, then call the tool by name' gives an explicit usage order and makes clear this is the entry point for the drive domain. It does not, however, mention sibling entry points like discover_all or google_api_call as alternatives, so the routing guidance is incomplete.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safe, repeatable nature is covered. The description adds that this reveals hidden tools and enumerates the revealed op catalog, which is useful context. However, listing destructive-sounding ops (trash, delete, send) without clarifying they belong to the revealed tools rather than this tool invites confusion.

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 purpose is front-loaded, which is good, but the long enumerated ops list is noisy and the trailing fragment '57 generated ops: users.' reads as truncated/unclear. The core message survives, but the tail does not earn its space.

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 discovery tool with no output schema, the description conveys the gist (a catalog of ops) but leaves the return shape and the meaning of the truncated 'users' fragment unclear. It is adequate but incomplete for an agent trying to act on the result.

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?

There is one optional parameter with 100% schema coverage ('Filter keyword'). The description adds no syntax or format detail about the query filter beyond the schema, so baseline 3 applies.

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?

States a specific verb+resource: it 'lists the catalog and reveals its hidden tools' for gmail, which is clear and actionable. It does not explicitly differentiate itself from sibling discovery tools like discover_all or calendar_discover, but the gmail scoping is 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?

'call first, then call the tool by name' gives a clear sequencing instruction for when to use this tool. It stops short of naming an alternative (e.g., discover_all vs gmail_discover) or stating exclusions, so it isn't a full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations, which only say destructive/non-idempotent/open-world: the description discloses the human-confirmation flow for writes (account, verb, params, destinations-first body summary) and the exact env-var gates (GOOGLE_PROFILE=full-writes with no allowlist, GOOGLE_READ_ONLY, GOOGLE_WRITE_DENY) that refuse calls. It also declares JSON-only output. This is consistent with destructiveHint=true and readOnlyHint=false, not contradictory.

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?

Four sentences, front-loaded with what it is, then discovery routing, then write/read behavior, then the binary exclusion. Every sentence carries information an agent needs to call it correctly; no restatement of the name or schema.

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 six-parameter, nested-object, open-world tool with no output schema, the description still covers discovery of methodIds, write-confirmation behavior, read payload sizing, return format, and where to go for binary content. An agent has enough to call it safely and correctly.

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?

Schema description coverage is 100%, so the baseline is 3; the description earns above that by documenting the `fields` query param trick for partial responses and implying queryParams is where read-side options go. It does not explain body vs pathParams vs queryParams beyond the schema, keeping it at 4 rather than 5.

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?

States a specific verb and resource ('Invoke any Google Workspace REST method by Discovery id') and immediately frames its role as an 'escape hatch for operations without a dedicated tool', which cleanly separates it from the many *_discover siblings. An agent knows exactly what class of operation belongs here.

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?

Gives explicit sequencing ('Find methods with google_api_search first'), an explicit when-not rule (prefer dedicated tools), and a concrete exclusion with alternatives ('for binary/file content ... use drive_download / drive_export instead'). Nothing about selection is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds real value beyond that by describing what is returned (method ids and parameters) and the workflow it feeds into, plus the full alias vocabulary. It does not mention result caps or pagination, so it is not fully transparent.

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?

Purpose and behavior are front-loaded in the first sentence, with the alias list trailing as reference data. The ~30-item alias list is long but functional since no enum is defined in the schema; it is justifiable rather than padding.

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?

No output schema exists, so the description carries the return-value burden and does describe the shape ('method ids + parameters'). Combined with full annotation coverage and documented parameters, an agent has enough to invoke correctly, though result-count and ranking behavior are unaddressed.

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?

Schema coverage is 67% (api and query documented, maxResults not). The description compensates by enumerating the accepted API aliases for the `api` filter, which the schema does not provide, and reinforces the query intent with 'method ids + parameters' output framing. It adds genuine meaning over the schema.

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?

Names the specific verb and resource ('Search the Google API Discovery index for any Workspace REST method') and immediately scopes it to methods with no dedicated tool. This distinguishes it from both the per-service *_discover siblings and google_api_call, which it explicitly hands off to.

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?

Explains the discovery-to-invocation workflow ('Returns method ids + parameters to invoke via google_api_call') and that it covers methods lacking a dedicated tool, which implicitly tells the agent when a dedicated sibling is preferable. It stops short of naming a specific alternative tool or stating exclusions explicitly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/idempotentHint true and destructiveHint false, so safety is covered. The description adds genuine behavioral context beyond them: that it enumerates a catalog plus hidden tools, and that it is the prerequisite entry point for named tool calls.

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?

Front-loads the purpose before the op enumeration, and every clause carries information. The long semicolon-delimited ops list is useful but slightly dense.

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 discovery tool with no output schema, the description adequately explains what it returns (catalog + hidden tools) and the follow-up workflow. It could note polling/refresh behavior or relationship to discover_reset, but nothing critical is missing.

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?

Only one parameter (query) with 100% schema description coverage, so the schema already documents it as a 'filter keyword.' The description adds no further semantics about its matching or format, which is the expected baseline when the schema fully covers the parameter.

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?

States a specific verb and scoped resource: 'Discover meet: lists the catalog and reveals its hidden tools.' The 'meet' scoping distinguishes it from gmail_discover/drive_discover siblings by resource, though it never contrasts with discover_all or discover_reset.

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?

Gives clear sequencing guidance ('call first, then call the tool by name'), telling the agent this must precede invocation of the enumerated ops. It stops short of explaining when to prefer it over discover_all or other parallel discover tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral context by stating that it reveals hidden tools and by enumerating the available operations, which helps the agent understand the effect and scope of the call beyond the safety annotations.

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 front-loaded with the core action and sequencing instruction, then supplies the operation list compactly. The list is long, but every item is useful for understanding what the tool reveals, and there is no redundant prose.

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 discovery tool with no output schema, the description gives an adequate sense of what is returned: a catalog and hidden tools, including the named operations. Combined with annotations covering safety, this is nearly complete, though it could clarify how to invoke the revealed operations by name.

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 input schema has 100% description coverage, and the single parameter is documented there as a 'Filter keyword.' The description does not add any additional meaning about the query parameter, so the baseline of 3 is appropriate.

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 states a specific verb and resource ('Discover searchconsole'), explains that it lists a catalog and reveals hidden tools, and identifies itself as the required first call. It clearly differentiates itself from sibling discovery tools such as gmail_discover and drive_discover by naming the searchconsole domain.

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 gives explicit sequencing guidance: 'call first, then call the tool by name.' This tells the agent when to use it relative to the hidden tools it reveals. It does not compare itself to discover_all or explain when not to use it, so it falls just short of full alternative coverage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered structurally. The description adds the useful behavioral fact that it "reveals hidden tools" and must be called first, which are beyond the annotations, but it omits anything about result format or how the revealed tools are namespaced.

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 purpose is front-loaded, which is good, but the trailing ops enumeration ("create, get, read_range... +20 more; 7 generated ops: spreadsheets") is dense and the phrase "7 generated ops: spreadsheets" is cryptic and adds noise rather than clarity.

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?

With no output schema, the description usefully states that it returns a catalog and reveals hidden tools, which tells the agent what to expect. The confusing ops/generated-ops tail and the absent guidance on the query filter keep it from being fully complete.

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?

Schema description coverage is 100%, and the single query parameter is documented as "Filter keyword" in the schema itself. The description contributes no additional meaning about what the query filters on, so the baseline 3 applies.

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?

States a specific action (lists the catalog, reveals hidden sheets tools) tied to the "sheets" domain, which reads clearly against siblings like gmail_discover or drive_discover. However, it never explicitly distinguishes itself from discover_all, which is the closest sibling and the obvious overlap risk.

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?

"call first, then call the tool by name" gives concrete ordering guidance for the two-phase flow. It lacks any exclusion or comparison to discover_all, so an agent can't tell when NOT to use this versus the aggregate discovery tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context by stating that the tool reveals hidden tools and must be invoked before calling those tools by name, though it does not cover return format, pagination, or auth details.

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 front-loaded with the core purpose and usage rule. The operation list is dense but useful for discovery; however, the inclusion of '+2 more' and generated ops adds minor clutter without fully earning its place.

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 simple read-only discovery tool with one optional filter parameter and no output schema, the description is largely complete: it explains what the tool does and when to call it. It could better clarify how the 'query' filter relates to the catalog, but the schema already covers that parameter.

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?

Schema description coverage is 100%, and the sole parameter 'query' is already documented as 'Filter keyword'. The description adds no additional meaning about the parameter, so the baseline of 3 applies.

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 names a specific verb and resource, 'Discover tasks', and explains the outcome: 'lists the catalog and reveals its hidden tools'. It also distinguishes the tool from the hidden tools it exposes by instructing the agent to 'call first, then call the tool by name'.

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?

The description gives clear sequencing guidance: 'call first, then call the tool by name'. It does not explicitly mention when not to use this tool or name alternatives such as discover_all, so it falls short of full when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds that it reveals hidden tools (useful), but says nothing about return shape, pagination, or how the revealed tools are surfaced. Modest added value over the annotations.

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?

Two compact sentences, front-loaded with the purpose and the sequencing instruction. The trailing 'Ops:' fragment is slightly garbled (claims 15 ops but lists four), though it stays brief.

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 single-parameter discovery tool with no output schema and annotations covering safety, the description is adequate: it names the resource and explains the call-first workflow. The incomplete/ambiguous ops enumeration is a minor gap.

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?

Only one optional 'query' parameter, and the schema already documents it as a 'Filter keyword' at 100% coverage. The description adds nothing about filter syntax, matching behavior, or empty-query semantics, so baseline 3 applies.

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?

Clear verb+resource: it lists a catalog and reveals hidden tools for the 'workspaceevents' service. The 'call first, then call the tool by name' line plus the ops list distinguishes it from direct action tools, though it does not distinguish it from its many *_discover siblings beyond the resource name.

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?

Gives one useful instruction ('call first'), implying a discovery-before-invocation workflow. But it offers no guidance on when to use this vs. discover_all or the other service-specific discover tools, and no exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.