Leadbase

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the call is free, 'available' excludes reserved credits, 'used' is settled usage only, percentages reflect current allocation not lifetime balance, and null means no allocation.

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 cost are front-loaded, followed by field semantics and the usage caveat. Four dense sentences, each carrying information, though the field-definition clauses make it slightly heavy for a zero-argument read.

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 an output schema present, the description need not enumerate return values, and it covers purpose, cost, field caveats, and when to check. It is complete enough for an agent to call and interpret 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 takes zero parameters, so there is nothing to document and the baseline is 4. The description correctly spends no space on parameter syntax.

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 opens with a specific verb and resource: 'Read the current workspace plan and credit balance.' An agent immediately knows exactly what this returns, and no sibling tool competes for this purpose (all siblings are sheets_/enrichment_ operations).

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 states when to use it ('Check this before planning more paid work') and adds a guardrail that balance does not authorize work beyond the user request. There is no named alternative, but none exists in the sibling set, so the routing context is adequate.

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 closed-world, so the safety profile is covered. The description adds genuine non-obvious behavior the annotations cannot convey: a Pending job 'continues independently of this connection', which tells the agent this is an async polling read rather than a synchronous result fetch.

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 tight sentences with the lifecycle caveat front-loaded after the core purpose. Minor overlap with the output schema in the final sentence, but every clause carries 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?

Return values are partly covered by the existing output schema, and the async lifecycle note is a strong addition. What's missing is the sourcing of batchId and the relationship to enrichment_list and enrichment_reconcile, which an agent needs to sequence these calls 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 0% — batchId has no description, no format guidance, and no hint about how to obtain it. The description never mentions the parameter, so it fails to compensate for the coverage gap, though it does at least imply the tool is keyed on a specific job.

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 ('Read') and resource ('a durable research job in the current workspace'), so the operation is unambiguous. It does not, however, distinguish itself from the neighboring enrichment_list or enrichment_reconcile, leaving the singular-vs-list distinction to be inferred.

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?

There is no explicit when-to-use guidance: nothing says to call this when you already hold a batchId versus using enrichment_list to discover one, and enrichment_reconcile is never mentioned as the alternative for resolving a settled job. The usage context is only weakly implied by the word 'Read'.

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 and openWorldHint=false, so the safety profile is fully covered by structured data. The description only adds that results are workspace-scoped and ordered by recency; it says nothing about pagination, how 'most recent' is bounded, or limit behavior, so it adds modest 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?

A single front-loaded sentence with no filler. It is efficiently sized for a simple list tool, though at this length the terseness is part of why other dimensions are thin.

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?

An output schema exists, so return values need not be explained. However, for a required-parameter listing tool the description omits the only input's semantics and any indication of result volume or ordering guarantees, leaving it minimally but not 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 0% and the single required parameter 'limit' (integer, 1-100) is never mentioned in the description. Since coverage is well under 50%, the description needs to compensate for the undocumented parameter but does not, leaving the agent to guess at the meaning and bounds of 'limit' and whether large limits are truncated.

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 ('List') and resource ('research jobs') scoped to the current workspace with an implicit ordering ('most recent'). The one wrinkle is that the tool is named enrichment_list while the description says 'research jobs', which sits alongside sibling tools like sheets_research/sheets_research_status, so the resource identity is slightly ambiguous, and no sibling (enrichment_get, enrichment_start) is named.

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?

No when-to-use guidance and no alternatives named. The agent is left to infer that this is the bulk-listing counterpart to enrichment_get, and there is no indication of when listing is preferable to fetching or starting a job.

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?

The annotations establish that this is a mutating, idempotent, non-destructive operation, but the description adds substantial behavioral detail beyond them: unknown usage stays pending, settled credits can increase only from confirmed existing receipts, interrupted attempts must reuse the idempotency key, and failed partial jobs remain failed even if billing settles.

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 opens with the core purpose, then layers in constraints and edge cases in descending priority. Every sentence carries information, and there is no filler or repetition of the schema or annotations.

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?

Given the output schema exists, the description need not explain return values. For this billing-reconciliation operation, it covers when to use it, what it will not do, how retries work, and how partial failures are treated, which is complete enough for correct invocation.

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 0%, so the description must supply parameter meaning. It does so for both parameters: jobId must identify a terminal job the caller created in this workspace and runtime, and idempotencyKey must be kept the same for an interrupted attempt.

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: reconcile billing for a terminal research job. It also scopes the job as one the caller created in this workspace and runtime, which clearly separates it from enrichment_start or enrichment_get.

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 an explicit precondition: use only when billingStatus is reconciliation_pending. It also states several when-not conditions (never starts, resumes, repeats research, purchases credits, or accepts caller-supplied costs). However, it does not name an alternative tool to use when the precondition is not met.

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?

Far exceeds what the annotations declare (destructive/idempotent/openWorld). It discloses that jobs run in the background, that Leadbase credits are consumed and completed usage is irreversible, that it does not send messages/purchase/execute arbitrary actions, that unknowns stay null/empty and fewer matches is a partial result, and that the call returns immediately after atomic batch acceptance. This is exactly the behavioral context an agent needs before committing spend.

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 the sibling alternative, then lifecycle, billing and recovery in a dense sequence. It is long, but nearly every sentence adds operational information (idempotency recovery, polling, credits) rather than padding, so the length is largely justified.

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?

Given a nested, credit-consuming, asynchronous batch tool with an output schema present, the description covers the full lifecycle: submission, atomic acceptance, polling via enrichment.get, billing settlement, and failure recovery. Nothing needed to invoke or follow up on 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 only 50%, so the description must carry weight, and it does: it explains that each item needs a unique id, task-relevant known facts, a question, and a typed output that is either a scalar or a list with named scalar fields and maxItems. It omits detail on the optional toolId field, so it is strong but not exhaustive.

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 ('research factual questions about companies, people, products or public web content for 1-100 independent inputs') and immediately contrasts itself with the sibling sheets.research. An agent can distinguish it from all the sheets_* enrichment 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?

Explicitly names the alternative ('Use sheets.research when the user wants a saved list'), gives the polling follow-up (enrichment.get with batchId until terminal and billingStatus settled), and prescribes exact recovery behavior for interrupted submissions (reuse idempotencyKey with unchanged items, never a new key). When-to-use and when-not-to-use are both 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 already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavioral context: it is a read-only entrypoint and does not incur paid research, and the query reaches sheets outside the initial page. The phrase "browse, search and edit" sits in mild tension with readOnlyHint, but the explicit "read-only entrypoint" clause resolves it.

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 tight sentences with the core action front-loaded and no filler. The only slight cost is the ambiguous "edit" in the opening sentence, which forces the reader to reconcile it with the following "read-only" clause.

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?

A rich annotation set plus an output schema mean safety and return values need not be re-explained, and the description covers the remaining gaps (read-only, no paid research, query reach). It is nearly complete for a single-optional-param entrypoint; only sibling routing is absent.

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 0%, so the description must carry the param meaning. It does: "Pass a query to search across the accessible catalogue, including sheets outside the initial page" explains both the query's function and its reach beyond the default page, which the schema's pattern/maxLength do not convey.

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 ("Open the connected Leadbase workspace") plus the scope of what the workspace enables (browse, search, edit sheets), which goes beyond simply restating the name. It does not, however, differentiate itself from overlapping siblings like sheet_workspace, workspace_search, or sheets_search.

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 one useful negative signal — "does not start paid research" — which implicitly routes cost-incurring work to sheets_research/enrichment_start. But it never states when to use this entrypoint versus the numerous search/list siblings, so usage is only implied.

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 the mutation profile (readOnly=false, destructive=false, idempotent=true), so the bar is lower. The description still adds real content beyond them: the typeLocked in-place restriction, the fact that returned IDs/option IDs are immediately reusable without a metadata reread, and the routing to copy_column for conversion. It does not discuss failure modes of the enrichment prompt itself.

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 sentences with the purpose front-loaded, then operational guidance, then the sibling escape hatch. Dense but each sentence earns its place. The first sentence is a long enumeration that could be tightened, keeping it short of a 5.

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?

An output schema exists, so return values need not be explained, and the description correctly focuses on mutation semantics, the typeLocked limitation, and ID reuse. The idempotency contract is left to the annotation and the idempotencyKey schema field rather than being discussed, which is a minor gap for a tool with 9 required parameters.

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 only 33% and several parameters (prompt, formatInstructions, contextColumnIds) carry no schema description at all, so the description has to compensate — and it does, naming enrichment prompt, output-format instructions, context-column scope, select options, and placement. That maps most of the 9 parameters to meaning beyond the raw schema, though it does not describe idempotencyKey or the constraint interplay between type and optionLabels.

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?

"Add one fully configured column" gives a specific verb+resource, and the enumerated sub-capabilities (enrichment prompt, output-format instructions, context-column scope, select options, placement) tell the agent exactly what 'fully configured' means. The closing sentence explicitly carves out the boundary with sheets_copy_column, so it is distinguishable from a sibling without opening either 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?

It names an alternative and the condition selecting it: a typeLocked column cannot change type in place, so use sheets_copy_column for conversion. It also gives workflow guidance (reuse returned IDs/option IDs, no metadata reread). However it offers no guidance for the more likely comparison set — sheets_update_column, sheets_rename_column, sheets_change_column_type — so exclusions are 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=false, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the 100-row ceiling and, more importantly, the retry protocol for reusing the idempotency key after an ambiguous outcome. It still doesn't say whether inserted rows are empty or what permissions are required.

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 short sentences, zero padding, with the row-count limit and placement scope front-loaded and the retry caveat second. 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?

An output schema exists, so return values need not be described, and the annotations carry the safety/idempotency profile. What remains is adequately covered: placement semantics, row limits, and retry behavior. The main gap is not distinguishing this mutation from sheets_insert_records and not noting whether rows are created empty.

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 only 25% (only idempotencyKey is documented), so the description should compensate more than it does. It does add real meaning for placement by explaining that a null/absent anchor means append at the end, and it restates the count cap of 100. But sheetId and the anchorRowId/side mechanics are left entirely to the schema's type and enum declarations.

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 (insert rows), plus concrete scope: up to 100, at the end or before/after an existing row. That positioning detail separates it from neighbors like sheets_move_rows and sheets_delete_rows. It does not, however, clarify how it differs from sheets_insert_records, which is the one sibling an agent is most likely to confuse it with.

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 only guidance is retry-related ('Reuse the same idempotencyKey when retrying'), which is useful but concerns idempotency mechanics rather than tool selection. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g. sheets_insert_records for rows carrying data), so the agent must infer the choice from the tool name alone.

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 useful behavioral facts beyond them — results are exact (not sampled), computed server-side, and capped at 20 metrics. However it does not explain the required expectedRevision parameter's conflict/staleness behavior, which is the one genuinely non-obvious behavioral trait an agent needs.

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 dense sentences with the aggregation capability front-loaded and no filler. The closing clause about snapshotRevision is terse enough to be slightly cryptic and would read better explicitly tied to expectedRevision, but nothing 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?

An output schema exists, so return-shape explanation is not required, and the description covers the operation set, the metric cap, and the exactness guarantee. The main missing piece, expectedRevision semantics, is real but is the only substantive gap for a read-only idempotent 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?

With 0% schema description coverage the description must compensate, and it partially does: it maps 'metrics' to the operation families and states the 20-metric cap, and 'filters or search' alludes to the query object's q field. It says nothing about expectedRevision (required, nullable, revision-matching semantics), alias uniqueness, or the 10-filter bound, leaving key parameters unexplained in both places.

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 (compute) and resource (exact server-side metrics) and enumerates the supported operations: row count, non-empty count, distinct count, and numeric sum/average/minimum/maximum. It clearly distinguishes the tool as an aggregation operation rather than a row-returning one, but never names a sibling such as sheets_query or sheets_search_rows to make the boundary explicit.

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 phrase 'over all rows matching bounded filters or search' implies the tool is for filtered aggregation, and 'Pin repeated analysis with returned snapshotRevision' hints at a repeated-analysis use case, but there is no explicit when-to-use versus sheets_query/sheets_search_rows split and no statement of exclusions or 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?

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds genuinely useful context those fields cannot convey: data and grants are preserved, only the owner can restore, and restoration is bounded by a retention period. It stops short of naming the retention window or who may archive.

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 zero filler, front-loaded on the action and its key constraint. Every clause carries information (non-deletion, owner-only restore, retention window).

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?

An output schema exists, so return values are covered elsewhere, and the description supplies the reversibility and retention story an agent needs for risk assessment. It omits who is permitted to archive and the retention duration, minor gaps for a two-parameter 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 coverage is only 50%: idempotencyKey is thoroughly documented in the schema, while sheetId carries no description. The description adds no parameter-level detail (no format, no idempotency guidance), but the one complex parameter is already well covered by structured fields, landing at the baseline.

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 ("Archive a sheet") and immediately qualifies the operation as non-destructive ("without deleting its data or grants"). This implicitly separates it from sheets_archive_folder (folder scope) and sheets_delete_rows, though it never names those siblings 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?

Usage is only implied: the non-deletion wording hints this is the reversible alternative to a destructive delete, and the owner/retention sentence describes the restore path. There is no explicit when-to-use vs. archive_folder or delete guidance, and no prerequisites for performing the archive itself.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful blast-radius information that annotations cannot convey: the entire subtree plus every active sheet within it is archived, and the 'owner-owned/owner-controlled' qualifier hints at an ownership prerequisite.

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?

A single front-loaded sentence with zero filler; the scope-defining clause is placed immediately after the core action.

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?

An output schema exists, so return values need no explanation, and the cascade scope is stated. However, for a destructive operation it omits the ownership/permission requirement, whether the action is reversible via sheets_restore_folder, and any partial-failure semantics when only some sheets qualify.

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 only 50%: idempotencyKey is fully documented in the schema, but folderId has no description at all. The description does not explain what folderId accepts or constrain it (e.g., must be a folder the caller owns), so it fails to compensate for the coverage gap.

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 (Archive) and precise resource (folder subtree), and clarifies the cascade scope with 'all owner-owned active sheets inside it.' It implicitly distinguishes itself from sheets_archive (single-sheet) and sheets_restore_folder, though it never names those 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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as sheets_archive for a single sheet, sheets_restore_folder for reversal, or sheets_list_archived. The agent must infer selection from the name alone.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing blast radius: sibling cells continue independently and already-committed applications stay in sheet history, which tells the agent the cancellation is partial and non-retroactive.

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 short sentences, front-loaded with the action and scope, then the consequence. No filler and no restatement of the name or 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?

An output schema exists, so return values need not be explained, and the description covers the key behavioral risk (partial cancellation, history preserved). The remaining gap is the lack of guidance on when to invoke this versus an undo/restart path, which matters for a destructive mutation.

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 only 33%, so the description must compensate and it only partly does: it clarifies runId semantics (identifies the single run to cancel) but says nothing about sheetId, and it is silent on the required idempotencyKey even though idempotentHint is false.

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 (cancel), a precise resource (one cell run), and the identifier it acts on (run ID). The scope qualifier 'exactly one' cleanly separates it from any batch/worksheet-level cancellation an agent might otherwise assume.

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 implied usage (cancelling an in-flight cell run when its run ID is known) is discernible, but the description names no alternative tools and no when-not condition — e.g. it never says what to do after cancelling or how it relates to sheets_restart_version_restore or undo paths.

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 destructiveHint=true and idempotentHint=true, so safety and retry semantics are covered structurally. The description adds genuinely non-obvious behavior: the typeLocked gate and the fact that clearing all values does not unlock the type. It stops short of stating auth/permission requirements or what the mutation returns (though an output schema exists).

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 dense sentences with zero filler: the precondition comes first, the irreversibility consequence second, and the redirect to copy_column last. Every clause carries actionable 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 destructive six-parameter mutation the description covers the key gating rule and the escape hatch, and an output schema is present so return values need no prose. The main residual gap is the optimistic-concurrency contract behind expectedColumnVersion, which an agent must get right to call this successfully.

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 low (33%), yet the description explains no parameters at all. Critically, expectedColumnVersion is undocumented in both places despite being required concurrency control, and optionLabels' relationship to select/multi_select target types is only implied by the schema. The targetType enum is well documented in the schema itself, so the description compensates for nothing.

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 precise verb+resource ('Change a column's type') and immediately differentiates from the sibling conversion path by naming copy_column. An agent can distinguish this from sheets_update_column or sheets_copy_column 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?

Gives an explicit precondition ('only while typeLocked is false'), an explicit when-not ('Once populated, its type remains fixed even after every value is cleared'), and names the alternative tool (copy_column) plus its advantage (preserving the source). This is the when/when-not/alternative trifecta.

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?

Adds substantial behavior beyond the annotations (destructive, idempotent, openWorld): paid research consumes Leadbase credits without another call, only empty cells with usable context are researched and existing values are preserved, disabling does not cancel or reverse started runs, and it requires edit access plus the current column version. This is exactly the extra context a mutation tool needs.

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?

Dense but front-loaded: the core enable/disable action and its credit implications lead, with prerequisites and idempotency guidance trailing. Every sentence carries operational meaning, though the paragraph is long and could be broken up for scanning.

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 destructive, credit-consuming mutation with an output schema present, the description covers cost, eligibility, irreversibility of disabling, access/version prerequisites, idempotency recovery, and where to inspect status or cancel. Nothing an agent needs to call it safely 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?

With 50% schema coverage, the description meaningfully compensates: it explains requiredColumnIds as all-must-be-present prerequisites and instructs using [] when none are requested, and explains the idempotencyKey reuse rule and expectedColumnVersion requirement. The semantics of enabled and the version param are reinforced in prose.

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 pair (enable/disable) and resource (ongoing, paid web research for one sheet column using its configured question and type). The 'ongoing/automatic' framing separates it from one-off siblings like sheets_enrich and sheets_start_enrichment without needing 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?

It gives an explicit usage condition ('Enable only when the user requests automatic research') and routes the agent to sheets.get_enrichment_status for runs/costs and sheets.cancel_enrichment for cancelling. It stops short of explicitly contrasting with the sibling one-time enrichment tools, so the routing is clear but not exhaustive.

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 declare the coarse profile (write, idempotent, non-destructive); the description adds substantive traits: the operation is snapshot-based and preserves the source, invalid values are omitted and reported rather than failing the whole job, and the call is asynchronous, returning a durable job ID. That is exactly the extra context an agent needs to handle partial results and polling.

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, each carrying distinct load: operation semantics first, then side-effect/failure behavior, then follow-up routing. No repetition of the title or name, 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 mutation tool with an output schema (so return shape needn't be explained) and annotations covering safety, the description is nearly complete — async model, invalid-value handling, source preservation, and cleanup path are all covered. The remaining gap is concurrency/versioning behavior, which is left entirely to an undescribed 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 only 43%, and the description never compensates: 'typed column' hints at the type parameter but says nothing about expectedColumnVersion (an optimistic-concurrency token), selectOptions, or name. With only idempotencyKey and type documented in the schema, an agent must infer the meaning of the concurrency guard and the option catalog.

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 ('Copy a consistent snapshot of a column into a new typed column') and pins the output target, which distinguishes it from sheets_change_column_type (in-place retype) and sheets_add_column (empty column). An agent can select it without opening any sibling 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 routes the agent for follow-up work: 'Use get_column_copy for completion; undo the resulting add_column changeset to remove the copy.' It gives clear post-invocation context but never states when to prefer this over alternatives like retyping an existing column, so the routing is one-directional.

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 idempotentHint=true, destructiveHint=false, and openWorldHint=false; the description goes beyond them with concrete retry semantics ('reuse the same idempotencyKey and payload on retry') and states that a successful creation receipt obviates a second metadata read. It doesn't cover permission/visibility effects or failure modes, so a 4 rather than a 5.

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 tight sentences, front-loaded with the selection condition before the workflow and retry guidance. No filler, though the retry sentence is dense enough to warrant a second read.

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?

An output schema exists so return values need not be explained, and the description covers the create-then-populate workflow, retry behavior, and the receipt shortcut. The undocumented folderId/visibility parameters remain a minor gap for a 4-required-param 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 50%; title and idempotencyKey are documented in the schema, while folderId (including its null variant) and visibility are not. The description reinforces idempotencyKey retry usage but adds nothing for folderId/visibility, so it neither fully compensates nor is empty.

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 ('Create a new empty sheet') and even bounds the scope ('only when requested or no existing destination applies'). It does not explicitly differentiate itself from near-siblings like sheets_duplicate or sheets_insert_records, so it stops short of a 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?

Gives an explicit when-to-use condition ('only when requested or no existing destination applies') and then prescribes the follow-up workflow (use returned ID to add schema and records in the same execution). An agent can decide whether to reach for this tool versus reusing an existing sheet without 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 destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the safety and idempotency profile is largely covered by structured data. The description restates idempotency ('same idempotency key return the same folder') with slightly more concrete wording, but says nothing about permissions needed to create a team-visible folder, name-collision behavior, or 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 compact sentences with no filler; the core action and its two main modifiers are front-loaded, and the idempotency note is a single tight clause. Nothing is repeated or padded.

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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. For a create mutation the description is nearly complete, with only minor gaps around permissions for team visibility and duplicate-name handling.

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 50%: name and idempotencyKey are well documented in the schema, while visibility and parentFolderId are not. The description partially compensates by spelling out the private/team choice and the optional parent folder, but this largely restates the enum values and the nullable anyOf, adding little beyond the structured fields.

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 ('Create ... folder') and immediately scopes it with the visibility options and optional nesting, which is enough for an agent to identify the operation. It does not explicitly differentiate itself from the many folder siblings (rename_folder, archive_folder, move_to_folder, get_folder), so the distinction rests on the verb alone.

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 phrase 'optionally nested under a visible folder' implies when to supply parentFolderId versus leaving it null, which is useful implied guidance. However, there is no explicit when-to-use or when-not-to-use statement and no routing to alternative tools such as sheets_move_to_folder or sheets_rename_folder for adjacent folder operations.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful behavior: the snapshot is immutable (the saved version will not drift with later edits), and the call enforces optimistic concurrency by requiring the revision to match current state. It stops short of describing failure behavior on stale revisions or name-collision handling.

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 zero filler; the core action and content of the snapshot are front-loaded, and the revision constraint follows immediately. Every clause carries information the 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?

An output schema exists, so return values need no explanation, and idempotency-key semantics are fully documented in the schema. For a 4-required-param mutation the description is nearly sufficient, missing only edge-case behavior (stale revision, duplicate version names) and how to obtain the current revision.

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 50%: 'name' and 'idempotencyKey' are documented in the schema, while 'sheetId' and 'revision' have none. The description partially compensates by explaining revision semantics ('must match the current sheet revision'), but adds nothing about sheetId resolution or name uniqueness/constraints, leaving half the parameters carried by structured fields alone.

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 ('Save an immutable snapshot of the current sheet') and enumerates what the snapshot captures (cells, columns, options, views), which is far more than a restatement of the name. It does not explicitly contrast itself with siblings such as sheets_list_named_versions, sheets_rename_named_version, or sheets_restore_version, so it lands at clear-but-undifferentiated.

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?

Usage is only implied: the tool is for snapshotting current sheet state, and the hard prerequisite 'The revision must match the current sheet revision' tells the agent one condition of use. There is no explicit when-to-use vs. alternatives (e.g., sheets_create, sheets_restore_version) and no statement of when not to call it.

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 idempotentHint=true, destructiveHint=false and openWorldHint=false, so the mutation profile is known. The description adds real value beyond that: the optimistic-concurrency requirement (viewsOrderVersion) and the non-obvious side-effect note that creating a view never changes a person's currently open tab.

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 dense sentences, front-loaded with the action and scope before the prerequisites. Nothing is wasted, though the imperative list is packed tightly enough to read as a run-on.

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?

An output schema exists, so return values need no explanation. For an 8-required-parameter mutation with nested filter unions, the description covers the critical setup steps (read-first, IDs, version token, name uniqueness) but leaves the bulk of filter/sort construction to the schema.

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 low (25%), so the description must compensate, and it does partially: it flags that IDs must be exact, that viewsOrderVersion is required, and that name uniqueness is case-insensitive (a constraint not in the schema, which only enforces whitespace trimming). However, the elaborate filters union, sort's max-3 limit, and columnOrder/hiddenColumns semantics are left entirely to 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?

States a specific verb and resource (create a shared saved view) plus a scope constraint ('containing only filters and sorting'), which cleanly separates it from sheets_update_view, sheets_delete_view and sheets_reorder_views in the sibling list.

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 an explicit prerequisite workflow: read sheets.get first, use exact column/option IDs, pass metadata.viewsOrderVersion, pick a case-insensitively unique name. It doesn't explicitly contrast with sheets_update_view or state when not to create a view, so it stops short of 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 idempotentHint=true and destructiveHint=false, and the description explains why that framing is coherent: the deletion is a 'reversible changeset.' It also adds two behavioral facts the annotations do not cover — the optimistic-concurrency version requirement and the invariant that at least one column must survive. Only the recovery path for an ambiguous outcome is left unstated.

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, each earning its place: the first defines the operation and its reversibility, the second carries the concurrency and invariant constraints. The core action is front-loaded with zero preamble.

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?

An output schema exists, so return-value explanation is unnecessary, and the annotations carry the safety profile. The description supplies the key mutation-specific context (version passing, minimum-column invariant). It stops short of mentioning the undo/recovery route or what the changeset receipt contains, which would matter for a destructive-shaped operation.

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 25%: only idempotencyKey is documented in the schema, and sheetId/columnId/expectedColumnVersion carry no in-schema description. The description partially compensates by explaining that the column's entityVersion must be passed, but it uses a different name than the schema's expectedColumnVersion and says nothing about the format or semantics of sheetId/columnId, so the gap is only half closed.

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 ('Delete one column and its cells'), plus the scope of the mutation ('as one reversible changeset'). This cleanly distinguishes it from row-oriented siblings like sheets_delete_rows and from non-destructive column operations like sheets_rename_column or sheets_archive.

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 an implicit precondition ('a sheet must retain at least one column') and tells the caller to pass the column's version, which frames when the call is valid. However, it never names an alternative (e.g. archiving, or restoring via sheets_undo) or states when to prefer this over them, so usage is only implied.

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 declare destructiveHint=false and idempotentHint=true, and the description explains why a delete is non-destructive ('reversible changeset'), which is genuinely additive context. It also discloses the 500-row cap and the revision precondition (optimistic concurrency). It doesn't cover failure modes such as a stale revision or a row ID that no longer exists.

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, zero filler: the operation, its size limit and reversibility come first, then the call-order prerequisite. Front-loaded and every clause carries 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?

An output schema exists, so return values need no explanation. For a mutation tool the description covers the important agent-facing facts: reversibility, batch limit, and the read-then-pass-revision workflow. It stops short of stating what happens on revision mismatch or partially invalid row IDs, which is 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?

Schema coverage is only 25%, so the description must compensate, and it does for three of four parameters: 'current revision' explains expectedRevision's optimistic-lock role, 'stable row IDs' characterizes rowIds, and 'up to 500' restates maxItems with meaning. Only sheetId is left implicit, which is self-evident.

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 (delete) plus resource (rows), scope (up to 500 explicit rows) and the atomic unit ('one reversible changeset'). That combination cleanly separates it from sheets_delete_column, sheets_move_rows, and sheets_archive without needing to name a sibling.

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 an explicit prerequisite sequence: read/query the sheet first, then supply the current revision and stable row IDs. It tells the agent how to prepare a valid call, but never names the alternative tools (e.g., delete_column, archive, move_rows) or the conditions that select them.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds value beyond them by bounding the blast radius (rows/columns/cells untouched), stating the invariant that one view must survive, and pointing at sheets.get for the optimistic-concurrency token.

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 with the core action front-loaded and no filler. The 'including the first' clause is slightly awkward phrasing but does carry a distinct constraint, so it earns 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?

An output schema exists, so return-value documentation is not required, and annotations carry the safety/idempotency semantics. The description covers the destructive scope, the remaining-view invariant, and version sourcing — an agent has enough to invoke it correctly, though the two UUID identifiers are unexplained.

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 only 25% (only idempotencyKey is documented), so the description must compensate. It does explain the provenance of expectedVersion ('the current view version from sheets.get'), but viewId and sheetId are left entirely implicit, so it only partly fills the gap.

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 ('Delete ... saved view') and immediately scopes it ('without changing rows, columns, or cells'), which cleanly separates it from sibling mutation tools like sheets_delete_rows, sheets_delete_column, and sheets_update_view. The phrase 'any shared saved view, including the first' also tells the agent there is no protected default view.

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 a real precondition ('At least one saved view must remain') and routes the agent to sheets.get for the required version value, which is genuinely actionable. It stops short of naming alternatives such as sheets_update_view or sheets_reorder_views when the intent is to modify rather than remove a view.

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 cover safety (destructiveHint=false), idempotency, and closed-world scope, so the bar is lower; the description still adds real value by disclosing what is NOT carried over (history, sharing) and that the copy gets its own ownership. It omits what happens to folder placement or whether the copy needs a name.

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, front-loaded with the action and scope, then the exclusions. No filler or restatement of the 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?

An output schema exists so return values need not be explained, and annotations cover idempotency. The copy/exclusion semantics are present; only destination placement and any naming or permission requirements for the resulting sheet 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 50% (idempotencyKey is richly documented, sheetId has none). The description hints that sheetId identifies a 'readable' source sheet, adding a permission implication, but gives no naming, placement, or output-target semantics beyond that.

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?

Specific verb (duplicate) plus resource (sheet), with scope defined as the 'current state' and the result framed as an 'independently owned sheet'. It also implicitly distinguishes itself from copy-type siblings by stating that historical versions and sharing are excluded.

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 no when-to-use guidance, no prerequisites, and does not name any alternative such as sheets_create, sheets_copy_column, or sheets_transfer_ownership. The agent must infer that this is the tool for producing a standalone full-sheet copy.

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 flag destructiveHint=true, readOnlyHint=false, idempotentHint=false, openWorldHint=true, so the mutation risk is largely covered elsewhere, and the description is consistent with them ('Enable' is a write). It adds real context by specifying the exposure is public and unauthenticated, but omits what the agent most needs beyond annotations: that the change is reversible only via a separate revoke tool, that an expectedAclVersion mismatch aborts the write, and that annotation idempotentHint=false is mitigated by the idempotencyKey parameter.

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?

One short, front-loaded sentence with zero filler; the scope qualifier ('public, unauthenticated read') arrives immediately. It is efficient rather than padded, though that economy is also the source of its under-specification.

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?

An output schema exists, so return-value explanation is not required, but for a destructive, non-idempotent, world-visible ACL mutation with three required parameters and 33% schema coverage, the description is far too thin: no concurrency semantics for expectedAclVersion, no reversal path, no note on who gains access or how to audit it.

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 only 33% — just idempotencyKey is documented — and the description adds nothing at all about parameters. sheetId and expectedAclVersion are unexplained in both places, leaving the optimistic-concurrency contract (the acl version token) entirely invisible to the caller.

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+scope: 'Enable public, unauthenticated read access to a sheet.' An agent can infer this differs from sheets_set_team_access or sheets_share_with_email by the 'public/unauthenticated' qualifier. It stops short of naming those siblings explicitly, which keeps it from a 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?

No when-to-use, when-not-to-use, or alternative guidance is given. It never mentions the counter-operation (sheets_revoke_publication) or which sharing tool to pick when the audience is a team or a named person. Nor does it state prerequisites such as ownership or admin rights needed to loosen a sheet's ACL.

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 flag destructive/inverse-of-readOnly behavior, but the description adds substantial context: it consumes Leadbase credits, completed usage cannot be undone, existing values/active cells are skipped, a new column is persisted before research starts, and it is asynchronous ('Returns accepted runs, not finished results'). The idempotency-key-on-retry instruction is equally non-obvious and valuable.

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 the purpose, then layered routing, constraints, and retry guidance — every sentence carries a distinct operational instruction. It is dense and longer than typical, but almost no sentence is redundant.

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 paid, async, destructive enrichment tool this covers everything an agent needs: scope, skip semantics, credit cost, irreversibility, alternative tools, and the follow-up path to status/query. An output schema exists, so return-value details need not be restated, and the description still correctly notes it returns accepted runs rather than results.

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 only 50%, and the description compensates by explaining the anyOf shape of 'column' (existing columnId with its configured question/type vs. a new name/question/type) and the exact semantic of omitting rowIds. The 'type' enum values themselves are documented only in the schema, so the description doesn't add on that axis.

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+scope: 'Fill empty cells in one column of an editable sheet through paid web research using each row's existing context.' It also distinguishes itself from near-siblings (sheets.research, sheets.start_enrichment) that an agent would otherwise confuse it with.

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 routing: use sheets.research for new result rows, sheets.start_enrichment for multi-column targets or replacement of existing values. It also states the omission rule for rowIds ('omit only when the user requests all existing rows') and names the follow-up tools (get_enrichment_status, query) for progress and results.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds that the export is bounded and UTF-8, but it does not explain revision conflicts, error behavior, or what happens when maxBytes is exceeded.

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 direct sentences with the core operation front-loaded and no wasted wording. The larger-sheet fallback follows immediately as actionable context.

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?

The output schema means return values need no explanation, but the description does not cover expectedRevision, which is required for correct invocation. For a tool with three required parameters and 0% schema description coverage, this is a significant completeness 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 0%, so the description must compensate for three required parameters. It hints at maxBytes ("bounded") and sheetId ("current sheet"), but expectedRevision is never mentioned, leaving a required concurrency parameter completely unexplained.

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 (Export), resource (current sheet), scope (bounded), and format (UTF-8 CSV). It also distinguishes the operation from handling larger sheets, so an agent can tell what this tool is for 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?

It gives a clear condition and an alternative: use this for bounded current sheets, and for larger sheets query pages and assemble CSV in CodeMode. It does not name the exact sibling tool or provide any other when-not guidance, so it is helpful but not fully explicit.

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 non-destructive, and an output schema exists, so the safety and return-format burdens are largely carried elsewhere. The description still adds workflow context (pre-edit metadata fetch, preserving existing schema/data) that is not encoded in any structured field.

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 tight sentences, front-loaded with the primary purpose, then constraints, then alternatives. No filler or restatement of the 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?

For a one-parameter, read-only metadata getter with an existing output schema and full annotation coverage, the agent has everything needed: what it returns, when to call it, and what to call instead.

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 0% and the single sheetId parameter is never mentioned in the description. The schema's format:uuid gives partial signal, but the description does nothing to clarify the identifier, so it neither compensates nor adds value here.

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 (Get) and resource (sheet metadata) and enumerates exactly what comes back: column types, stable IDs, option IDs, versions. It explicitly distinguishes itself from sheets_query for cell values and from create/add-column receipts for newly created sheets, so an agent can route correctly 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?

Gives an explicit when-to-use trigger (read metadata before editing an existing sheet) and names two alternatives with the condition that selects them: reuse receipts for fresh sheets, and sheets_query for cell values. This is close to a complete routing rule.

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, and openWorldHint=false, so the safety profile is fully covered. The description adds one genuinely useful trait beyond the annotations, that invalid-value examples are bounded, but discloses nothing about auth, latency, or how progress/completion is represented.

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?

A single efficient sentence with no filler, and the key traits (progress, completion, bounded invalid values) are front-loaded. It is well-sized, though the terse phrasing sacrifices routing and parameter information that a slightly longer sentence could carry.

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?

An output schema means return values need not be explained, but with 0% parameter coverage on two required UUIDs and no link to sheets_copy_column, the agent lacks the context needed to obtain a valid jobId or decide when this call is appropriate.

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 0%, so both required parameters (jobId, sheetId) are undocumented anywhere. The description mentions a 'column copy' job indirectly but never maps meaning onto jobId or sheetId, leaving the agent to guess which UUID is the copy-job identifier versus the sheet.

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 (Read) and resource (durable column copy) plus what it reports: progress, completion, and invalid-value examples. It clearly reads as a status/result lookup, but it never names the sibling that initiates the copy (sheets_copy_column), so an agent must infer the pairing from the name alone.

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?

There is no explicit when-to-use guidance. The description implies this is a polling/result-read for a previously started column copy, but it never says to call it after sheets_copy_column, nor when to stop polling or what to do on an incomplete job.

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 cover the safety profile (readOnly, idempotent, non-destructive), but the description adds substantive behavioral context: the proposals 'have not been applied', the returned evidence fields, and the 'cite only sources supporting the proposed outcome' constraint. It stops short of documenting pagination or limits on the returned set.

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 compact sentences, front-loaded with the read scope followed by return fields and then the usage constraint. No filler, though the return-field listing is somewhat 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?

An output schema exists, so return values need not be explained, yet the description still enumerates them and ties the tool to the review workflow. Combined with the read-only annotations, an agent has what it needs, with only minor gaps around result limits.

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 0%, so the description carries the burden. It implies the two parameters ('specified sheet rows', sheet context) but adds no detail on the rowIds array constraints (uuid format, 1–500 items) or the sheetId format, leaving the schema to do most of the work.

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+scope: 'Read attached, completed enrichment proposals for the specified sheet rows.' This clearly distinguishes it from siblings such as sheets_review_enrichment_proposals and sheets_get_enrichment_status without needing to open 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?

Names the downstream tool explicitly ('Review with sheets_review_enrichment_proposals') and adds a prohibition ('never copy proposals into unfenced cell writes'), which directs correct usage. It does not state explicit exclusions or when not to call it, so it falls short of 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?

Annotations already cover the safe-read profile, and the description still adds substantial behavioral context: counts cover the entire selected scope, offset/limit page newest-first, each runId maps to exactly one cell, null evidence or empty sources mean no citation. The billing semantics are especially valuable: settledCredits is the confirmed subtotal (never a quote), pending=true means accounting is incomplete even if the subtotal is zero, and only pending=false establishes a final total.

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 is front-loaded in the first clause, and the remaining sentences are dense with load-bearing information rather than filler. It is long (roughly ten clauses) and shifts without signposting between scope, pagination, evidence, billing, and exclusions, but every sentence earns 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?

An output schema exists, yet the description still explains the semantics of returned fields (evidence, sources, billing.settledCredits, billing.pending) which the schema alone could not convey. Combined with the scoping exclusions and pagination contract, an agent has enough to invoke and interpret the call correctly; only the sibling routing gap remains.

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 0%, so the description carries the burden and largely does: rowIds and rowRange intersect when both are supplied, null means unrestricted, and offset/limit page individual runs newest first. sheetId and columnIds are not described, but 'for a sheet' and 'counts by column' make them self-evident. Numeric bounds are left to 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?

Opens with a specific verb+resource+scope: 'Read current cell-run status and counts by column for a sheet, explicit row/column IDs, or a row range.' An agent knows exactly what it gets. However, it never names or contrasts with the many sibling status tools (enrichment_get, enrichment_list, sheets_get_enrichment_proposals), so disambiguation from siblings is left to inference.

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 offers one concrete routing rule ('Read saved values through sheets.query and distinguish unapplied proposals') and a scoping exclusion ('No batch IDs, staff diagnostics, paid work or replay'). But much of the guidance is about interpreting returned data rather than when to call this tool versus enrichment_get, enrichment_list, or sheets_get_enrichment_proposals. Usage is implied rather than explicit.

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 closed-world, so the safety profile is covered. The description adds the "visible" scope qualifier (implying archived folders are excluded) and that only the first sheet page is returned, but it does not explain pagination continuation or auth requirements beyond what annotations supply.

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?

A single, front-loaded sentence enumerating the returned artifacts with zero filler. It is tightly sized for a low-complexity read 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?

An output schema exists, so return values need not be detailed, and annotations cover the safety profile. What is missing is how the "first sheet page" relates to the sheets_list_folder_page sibling for retrieving further pages, which an agent needs to avoid truncated results.

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 parameter (folderId, uuid string) with 0% schema description coverage, and the description adds no meaning beyond the name. Fortunately the parameter is largely self-evident, so no strong compensation is needed, matching the baseline for a single well-named required 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?

Specific verb+resource ("Get one visible folder") plus an enumeration of what is returned (breadcrumbs, direct child folders, first sheet page). This distinguishes it from generic siblings like sheets_get and sheets_list, though it never names those alternatives 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?

No when-to-use or when-not-to-use guidance is offered. The mention of "first sheet page" hints that a sibling (sheets_list_folder_page) handles continuation, but the description never states this relationship or any precondition for calling the 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, and openWorldHint=false, so the safety profile is covered. The description adds only the 'committed' qualifier and does not disclose return format, auth needs, or retrieval constraints beyond what annotations provide.

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 a single, front-loaded sentence with no filler or repetition. It states the core operation immediately and efficiently.

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 operation with an output schema and rich annotations, the description is minimally sufficient to identify the tool. However, it omits how to obtain a valid revision and does not clarify its relationship to sibling history/version tools.

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 0%, and the description does not explain the meaning, source, or expected format of 'revision' or 'sheetId' beyond the schema types. With two required parameters and no textual parameter guidance, the description fails to compensate for the coverage gap.

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 gives a specific verb ('Get') and resource ('one committed sheet history revision'), making the operation clear. It implicitly distinguishes from list-style siblings by saying 'one,' though it does not name an alternative tool 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?

There is no explicit guidance on when to use this tool versus siblings like sheets_list_history or sheets_get_version_restore. The intended workflow—likely list history then fetch a specific revision—is only implied, not stated.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds only the enumeration of what the ACL read surfaces, which is modest added value; it does not mention permissions required or freshness of the ACL data.

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?

A single compact sentence with zero filler, front-loading the verb and the returned ACL components. It is a fragment rather than a full sentence, but nothing 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?

An output schema is present, so return values need not be re-explained, and the annotations carry the safety profile. For a single-parameter read of sharing metadata, the description plus structured fields cover what an agent needs to invoke 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?

Schema description coverage is 0%, so the sole parameter (sheetId, uuid) is undocumented in both schema and description. The parameter is largely self-evident from its name and format, so the description's silence is a gap but not crippling; baseline 3.

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 ('Read') and the resource it operates on (a sheet's sharing/ACL data), and enumerates the components returned (users, invitations, team access, publications, owner, ACL version). It is clear what the tool does, though it does not explicitly distinguish itself from near-neighbors such as sheets_get or view_sheet.

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 offers no when-to-use or when-not-to-use guidance and names no alternative. With siblings like sheets_get_team_access-style read tools in the list, an agent gets no routing help from this text.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds the useful semantic that the job returned is the 'active or most recent durable' one, but says nothing about what happens when no job exists or how job identity is reported.

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?

A single front-loaded sentence with no filler; it earns its place. It is arguably too terse for the information an agent needs, but nothing in it 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?

An output schema exists, so return-value explanation is not required, and annotations cover the safety profile. However, with 0% schema coverage and no usage context, the description leaves the agent without enough to confidently pick this tool over the restore-related siblings.

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 0% and the single required parameter (sheetId, uuid) is never mentioned in the description. The parameter is self-evident from its name, but the description does not compensate for the missing schema documentation as the guidelines require at low coverage.

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 ('Get') and resource ('durable version restore job') with a scoping qualifier ('active or most recent'). An agent can distinguish it from mutating siblings like sheets_restore_version and sheets_restart_version_restore, 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?

No indication of when to use this versus sheets_get_history_revision, sheets_list_named_versions, sheets_restore_version, or sheets_restart_version_restore. The 'active or most recent' wording implies polling a job, but that inference is left entirely to the agent.

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=false, idempotentHint=true, destructiveHint=false, but the description adds substantive behavior beyond them: atomicity, 'each batch is one reversible changeset', the retry contract for idempotencyKey, and concrete capacity ceilings (100k rows, 10k ops, byte boundaries). This is well above the lower bar set by 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?

Dense but front-loaded: purpose comes first, then value formatting, then batching limits, then idempotency. Every sentence carries actionable content, though the single run-on paragraph would benefit from bullet separation of the distinct constraint classes.

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 complex multi-nested mutation tool this is complete: an output schema exists so return values need no explanation, annotations cover the safety profile, and the description covers formats, placement, batching limits, reversibility, and retry semantics. An agent has everything needed to invoke 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?

With only 25% schema description coverage, the description carries most of the burden and does so well: null vs omit semantics, blank strings treated as empty, per-type value requirements (email/phone arrays, YYYY-MM-DD dates, select option IDs over labels), and placement behavior. It partly restates the rawValue schema prose, but genuinely compensates for the coverage gap.

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 (insert), resource (records), and scope (at the end, or immediately before/after an existing row) with the added qualifier 'atomically'. An agent can immediately distinguish this from sheets_update_cells, sheets_add_rows, and sheets_delete_rows 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 strong operational context: how to place records, how to size batches against explicit infrastructure limits, and when to reuse the idempotency key ('only when retrying the exact same record payload'). It never explicitly names an alternative tool or a when-not condition, so it stops short of fully routing the agent among siblings.

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, and openWorldHint=false, so the safety profile is fully covered. The description adds the 'visible/authenticated' scoping and the category structure, which is useful, but says nothing about pagination, result limits, or freshness that a catalogue listing would benefit from.

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?

A single front-loaded sentence led by the verb 'List', with the category enumeration earning its space by defining the output grouping. No filler or redundant restatement of the 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?

For a zero-parameter read tool with rich annotations and an output schema, the description covers scope and content adequately. Return values are handled by the output schema, though pagination behavior for a potentially large catalogue is left 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?

The tool takes zero parameters, so per the baseline this scores 4. There is no argument syntax for the description to clarify, and schema coverage is moot.

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 (List) and resource (authenticated user's visible sheet catalogue) and specifies the returned grouping (private, team, shared-with-me, public, recent) plus folders. An agent can tell it retrieves a catalogue rather than content. It stops short of naming siblings like sheets_search or sheets_list_archived, so it is clear but not sibling-differentiated.

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?

Usage is implied by the content description (browse what sheets exist), but there is no explicit when-to-use, no exclusions, and no named alternative among the many list/search siblings. The agent must infer that this is the browsing entry point.

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 the operation read-only, idempotent, closed-world, and non-destructive, so the safety profile is covered. The description adds non-obvious behavioral scope: results are limited to "owner-restorable" items (not everything archived) and include purge deadlines, which tells the agent the listing will surface retention pressure.

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?

A single front-loaded sentence with no filler and no repetition of the title. Every clause (list, archived roots, owner-restorable, purge deadlines) carries distinct 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?

An output schema exists, so return values need not be described; with zero parameters and full annotation coverage the description only needs to convey scope and it does. Minor ambiguity remains around "roots" (whether descendants are excluded) and result ordering/pagination, which the description leaves unstated.

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 and the schema coverage is 100%, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter detail is needed or missing.

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?

Specific verb ("List") plus a precisely scoped resource: archived sheet AND folder roots, restricted to "owner-restorable" items, returning purge deadlines. An agent can distinguish this from siblings such as sheets_list, sheets_list_folder_page, and sheets_restore 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?

Usage is implied by the qualifiers: you call this to discover archived items that are still restorable before a purge deadline. However, with ~60 siblings including sheets_restore and sheets_restore_folder, the description never states the follow-up or the when-not (e.g., use sheets_list for live sheets).

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, and openWorldHint=false, so the safety profile is fully covered without the description. The description's only added behavioral detail is that results are ACL-filtered, which is useful but thin; it says nothing about page size, exhaustion signals, or ordering.

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?

One sentence, front-loaded with the verb and resource, no filler or redundancy. Nothing could be trimmed without losing 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?

An output schema exists, so return values need not be described. However, for a cursor-paginated list tool the description omits the pagination lifecycle (initial call, termination condition) and any differentiation from the many other list-style siblings, leaving a real 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 0% for both parameters, so the description must carry the meaning. 'Inside a folder' loosely maps to folderId and 'next ... page' hints that cursor is a continuation token, but the schema allows cursor to be null and the description never explains that null starts the first page — the single most important usage detail for a pagination cursor.

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: 'Read the next ACL-filtered page of sheets directly inside a folder.' That is clearly a paginated folder-scoped list operation, and 'ACL-filtered' adds real meaning. It does not, however, distinguish itself from nearby siblings such as sheets_list, sheets_list_archived, or sheets_get_folder.

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?

There is no explicit when-to-use guidance and no named alternative. The word 'next' weakly implies this is a continuation call, but the agent is never told what to call first or how this differs from sheets_list or sheets_get_folder.

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 genuinely new behavior: results are committed-only, ordered newest first, and paged backwards via a revision cursor. It says nothing about rate limits, page-size behavior, or what happens at the end of history.

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, no filler, with the core action and ordering front-loaded before the pagination instruction. Every clause earns 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?

An output schema exists so return values need not be described, and annotations cover the safety profile; the cursor semantics are the one thing an agent could not get elsewhere and they are present. What's missing is a note on what a 'changeset' represents or whether sheetId scopes the listing, which would matter for correct invocation.

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 0%, so the description must carry parameter meaning, and it does explain that beforeRevision acts as a backward cursor into older history — useful beyond the bare 'numeric string or null' schema. However, sheetId and limit (including the 1-100 bound) get no semantic treatment, so the compensation is partial.

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 ('List committed sheet changesets') plus the ordering ('newest first'), which is enough to distinguish it from the singular sheets_get_history_revision. It stops short of naming that sibling explicitly, so an agent must still infer which of the history tools to pick.

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?

'Follow beforeRevision for older history' is a real usage hint that tells the agent how to paginate rather than why to pick this tool. There is no statement of when to use it versus sheets_get_history_revision, sheets_get_version_restore, or sheets_undo/redo, so the routing guidance is only implied.

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 and openWorldHint=false, covering the safety profile fully. The description adds only the nuance that names are 'permanent' and attached to 'committed' revisions, which helps distinguish named versions from transient history but is thin beyond that; no pagination, scope, or result-shape context is given.

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?

A single front-loaded sentence with no filler or redundancy. It is arguably too terse for the tool's place in a crowded namespace, but judged purely on economy and structure it is efficient.

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?

The tool is a simple one-parameter read operation with an output schema, so return values need not be explained, and annotations cover safety. However, nothing tells the agent how this list relates to sheets_list_history or the version-restore family, which is the main missing context for correct selection.

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 0%, so the description would need to carry parameter meaning, and it does not mention sheetId at all. The single parameter is a self-evident UUID identifier, so the name does nearly all the work, but the description adds nothing beyond 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?

States a specific verb (List) and a well-defined resource: permanent names assigned to committed sheet revisions, i.e. named versions. This is distinguishable from the other list siblings (sheets_list, sheets_list_history, sheets_list_archived), though the description never explicitly names those alternatives or uses the term 'named version' that the title and sibling tools (sheets_create_named_version, sheets_rename_named_version) use.

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?

There is no when-to-use guidance and no mention of alternatives such as sheets_list_history or sheets_get_version_restore. An agent must infer from the name alone whether this or a history-listing tool is the right call.

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 the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower, yet the description still adds real value: a 500-row cap, ordering and stable-row-ID preservation guarantees, and the requirement to pass the current sheet revision for concurrency control.

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 dense sentences with zero filler. The core operation and row-count limit are front-loaded, and the concurrency and ordering guarantees follow immediately.

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 mutation tool with an output schema (returns need not be described) and full annotation coverage, the remaining burden is behavioral, and the description covers the cap, ordering, ID stability, placement modes, and revision semantics. Adequate without over-explaining.

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?

With schema description coverage at only 20%, the description must compensate and largely does: it explains rowIds' 500 limit, that placement of null means append and otherwise takes an anchor/side, and that expectedRevision must be the current sheet revision. Only sheetId is left unaddressed.

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 (Move) and resource (rows) with concrete scope: up to 500 rows as one ordered block, placed before/after an anchor or appended. This clearly separates it from sibling mutations like sheets_delete_rows, sheets_add_rows, and sheets_insert_records, though it never names an alternative 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?

Usage is only implied by the mechanics described (before/after anchor, or append with null). There is no explicit when-to-use-this-vs-X guidance, no prerequisites, and no exclusions, leaving the agent to infer the tool's place among the many sheets_* siblings.

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, non-destructive, non-idempotent mutation, so the safety profile is covered. The description adds useful behavioral constraints (the destination must be a 'compatible visible' folder; null targets the library root), but says nothing about what changes on the sheet, permission needs, or how the declared non-idempotency interacts with the idempotencyKey.

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?

A single sentence that front-loads the primary action and folds the null-edge-case into the same breath. No filler, no redundancy.

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?

An output schema exists, so return values need not be described. For a three-parameter move operation with annotations covering the safety profile and the description covering destination semantics, the essential call information is 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 only 33%, so the description must carry weight; it does explain folderId's null semantics (library root destination), which the schema does not. It says nothing about sheetId or the idempotencyKey retry contract, leaving two of three parameters to the schema alone.

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 (move a sheet to a folder) and clarifies the null case as 'move it to its library root'. It is clearly distinct from siblings like sheets_move_rows or sheets_rename_folder, though 'compatible visible folder' is left undefined and no sibling is contrasted.

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 implicitly covers the two usage modes: pass a folder to move into it, or pass null to move to library root. However, it gives no guidance on when a move is appropriate vs. archiving, no exclusions, and no prerequisites (e.g., permission requirements).

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 cover the read-only/idempotent/non-destructive profile, yet the description adds substantial context beyond them: read page.cells[].value not rawValue, email/phone remain arrays, phone normalization rules, evidence.applied=false means an unapplied proposal, null evidence/empty sources yield no citation, and external source text is untrusted data never instructions (a prompt-injection warning). This is rich behavioral disclosure an agent could not infer from 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?

The core purpose is front-loaded and every sentence is substantive rather than filler. It is dense and hops between value semantics, evidence rules, pagination, and versioning, which makes it a long read, but no sentence is clearly expendable.

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?

An output schema exists, so return-value documentation is not strictly required, yet the description usefully clarifies the tricky value/rawValue and evidence semantics anyway. Given the tool's complexity, the main gap is the unexplained query sub-fields, but the 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?

Schema description coverage is 0%, so the description must carry the load. It explains some parameters well (snapshotRevision to reuse as expectedRevision, nextCursor as opaque, projecting only needed columnIds, expectedVersion 0 vs entityVersion for writes), but the nested query fields q, sort, filters, history, version, pageSize, direction and focusRowId are never given meaning. It compensates partially rather than fully for a deeply nested 4-parameter 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?

Opens with a specific verb and resource plus scope: 'Read one revision-consistent, bounded page of rows and sparse typed cells.' It further distinguishes itself from siblings by naming sheets_aggregate for counts/statistics and positioning itself as the tool for verifying saved values, so an agent can route without opening another 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 an explicit alternative ('Use sheets_aggregate for ordinary counts/statistics instead of scanning pages') and a usage directive ('For enrichment progress read values and presence, never sleep-wait inside execute'), plus how to paginate via nextCursor. It stops short of full when-not coverage (e.g., when to prefer sheets_get or sheets_search_rows over a full page scan), so it is strong but not exhaustive.

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 the safety profile (destructiveHint=false, idempotentHint=true), so the bar is lower. Still, the description adds nothing beyond the title — it doesn't say whether the changeset must first have been undone, what gets reapplied, or what happens if the changeset is not in an undone state.

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?

A single front-loaded sentence with no filler. It is appropriately sized, though its brevity is partly under-specification rather than disciplined editing.

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 mutating tool with three required parameters and heavy domain jargon, the description is far too thin. An output schema exists so return values needn't be covered, but the undefined 'acknowledged routine changeset' concept and the unstated precondition (an existing undone changeset) are real gaps.

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 only 33%: only idempotencyKey is documented, while sheetId and changesetId are bare UUIDs. The description provides no compensating explanation of what a sheet or changeset identifier refers to, so the description fails to fill the coverage gap.

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?

It names a clear verb ('Redo') and ties it to a specific object class ('undo changesets'), so the operation is identifiable. However, the qualifier 'acknowledged routine sheet undo changesets' is unexplained domain jargon that leaves the exact scope ambiguous, and it never names sheets_undo as the inverse sibling.

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?

There is no when-to-use guidance, no prerequisites, and no mention of the obvious alternative sheets_undo. The agent must infer the relationship between undo and redo entirely from the names.

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 destructiveHint=true, readOnlyHint=false and idempotentHint=false, so safety is covered. The description adds nothing beyond that: it never mentions the required expectedAclVersion concurrency token, what happens on a version mismatch, or that the idempotencyKey must be reused on retry after an ambiguous outcome — all real behavioral gaps for a destructive mutation.

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?

A single front-loaded sentence with zero filler; the operation and its scope lead. It is terse rather than padded, though the brevity borders on under-specification for a four-required-parameter mutation.

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?

An output schema exists so return values need not be described, but for a destructive tool with four required parameters this one-liner leaves out concurrency behavior, permission prerequisites, and how removal differs from downgrading access. Substantial gaps remain.

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 only 25% — only idempotencyKey is documented in the schema, while expectedAclVersion is a bare numeric-string pattern and sheetId/userId carry no prose. The description's mention of 'user' and 'sheet' faintly maps to two parameters but explains nothing about the ACL version token, so it fails to compensate for the coverage gap.

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?

Specific verb (Remove) plus resource (one direct user's access to a sheet), and the word 'direct' quietly separates this from inherited/team-level removal. It does not name the closest siblings (sheets_update_user_access, sheets_set_team_access, sheets_revoke_invitation), so an agent must infer the boundary, but the operation itself 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?

There is no when-to-use guidance, no statement of preconditions (ownership/permission required to remove someone), and no alternative named for reducing rather than removing access. 'One direct user's' is a scope constraint, not usage routing.

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=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. But the description adds nothing beyond them: it does not explain that idempotencyKey is required for safe retry, that expectedRevision enforces optimistic concurrency, or what happens on a revision conflict.

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?

A single three-word sentence with no padding or waste, and the key action is front-loaded. But it is under-specified rather than genuinely concise for a four-required-parameter mutation 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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. Still, for a mutation requiring idempotencyKey, sheetId, expectedRevision, and title, the description omits concurrency semantics, permission needs, and any failure behavior — an agent lacks enough to invoke it correctly under conflict.

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 only 50%: 'sheetId' and 'expectedRevision' have no descriptions at all, and 'expectedRevision' is a non-obvious optimistic-concurrency token. The description says nothing about any of the four required parameters, so it fails to compensate for the coverage gap.

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 verb and resource ('Rename a sheet'), which does separate it from siblings like sheets_rename_column, sheets_rename_folder, and sheets_rename_named_version. However, it is a bare restatement of the name/title with no added specificity about scope or effect, so it sits at the vague end of clear.

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?

No when-to-use, when-not-to-use, or alternative guidance is given. An agent cannot tell from the description whether to prefer this over sheets_update_cells or whether renaming requires preconditions; the sibling list is large and no routing information is provided.

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