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

With no annotations, the description carries the full burden, and it does well: it explains that a new empty worksheet is created, that sheet_id is required, title must be unique, index controls position, and the return includes the numeric sheetId. It stops short of discussing permissions or failure modes, but covers the core behavioral contract thoroughly.

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 compact yet information-dense, front-loading the core purpose before parameter details. Every sentence earns its place and there is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 3-parameter tool with no annotations and an output schema, the description fully covers purpose, all parameters, constraints, return summary, and relationships to sibling tools. An agent has everything needed to call it correctly and integrate it with adjacent operations.

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 explain every parameter. It does: sheet_id's URL format and requirement, title's uniqueness constraint with a pointer to list_sheet_tabs, and index's 0-based positioning with default append behavior. This adds substantial meaning beyond the raw 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?

The description uses a specific verb ('Add') and resource ('tab/worksheet') and clearly distinguishes it from cell-level operations like update_sheet_range. It states exactly what the tool creates and even contrasts it with what sibling tools cannot do.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly names alternatives and complementary follow-up steps: update_sheet_range cannot create tabs, so use this tool first and then write with update_sheet_range using a tab-qualified range. It also tells the agent to consult list_sheet_tabs to avoid title collisions, making usage conditions 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?

With no annotations, the description fully discloses behavior: deterministic placement, does not use auto-detection, grows grid if full, returns written range. No hidden surprises.

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?

Description is well-structured with purpose front-loaded, followed by placement logic, alternatives, and parameter details. Each sentence adds value, no fluff.

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?

Complete for a mutation tool with no annotations: covers placement behavior, grid growth, parameter details, alternatives, and return value. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must explain parameters. It explains sheet_id (required, from URL), values (ordered list, align with columns), and value_input_option (USER_ENTERED vs RAW). Tab is implied but not explicitly described; still clear from context.

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 (append) and resource (a single row to a tab), with precise placement logic. Differentiates from update_sheet_range and insert_sheet_rows by naming them as alternatives.

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 states when to use this tool (to append at bottom) and when not to (to write elsewhere, use update_sheet_range or insert_sheet_rows). Also advises reading the header row first for alignment.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces these by stating 'This reads the form; it never writes to it, and nothing here submits anything.' It adds detail on error handling (in-band status+detail with specific codes) and clarifies that post-submit surveys are counted but not expanded. This goes well beyond the annotations and gives the agent a clear behavioral model.

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 dense but every sentence serves a purpose: purpose, usage context, parameter sourcing, error semantics, and scope boundaries. It front-loads the core purpose and decision-driving summary line. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has an output schema (not shown here) but the description already describes what it returns (sections, fields, required flags, paths, choices) and how to interpret the summary. It covers error handling, the meaning of NOT_FOUND, and what it does not do (expand post-submit surveys). For a read-only inspection tool with clear inputs and outputs, nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must fully explain parameters. It clearly explains slug and job_posting_id, including where to find them in ats_fetch_board results. It does not explicitly explain response_format, though the enum (markdown/json) and default are self-evident from the schema. Since two of three parameters are thoroughly documented and the third is trivial, this is a strong score just short of 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Read'), a precise resource (one Ashby posting's application form), and exactly what it reports (every question verbatim, with section, field, type, required flag, path, and select choices). It clearly distinguishes from siblings like ats_fetch_board (which lists postings) and check_posting (which likely checks status) by focusing on the form content. No ambiguity.

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 explicitly states when to use it: 'Use this before building an application packet.' It explains that the summary line classifies the form and determines whether drafting time is needed, and it clarifies that this tool only reads and never submits. It also gives interpretive guidance for NOT_FOUND as a meaningful answer rather than an error, which helps the agent decide how to proceed.

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 signal read-only, idempotent, non-destructive behavior, and the description adds valuable context: it returns no postings, reports the board_name as the API publishes it, and explains what SLUG_NOT_FOUND or NOT_FOUND_OR_API_DISABLED actually mean operationally. No contradiction with annotations 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?

The description is dense without being bloated. It front-loads the core purpose, then lists return fields, parameter-sensitive behavior, and error semantics in a logical order. Every sentence contributes useful decision-making or interpretation 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?

For a read-only board check with an output schema, the description covers what the tool does, how it differs from siblings, what its return fields mean, and how to interpret error-like statuses. Nothing essential for correct invocation or interpretation 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 0%, so the description carries the burden. It explains the optional company parameter well, including its purpose and the NAME_MISMATCH outcome. The slug and platform parameters are less explicitly defined, though 'is this slug still a real board' and the platform enum provide baselines.

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 ('Check whether a board is still alive') and explicitly differentiates itself from sibling ats_fetch_board by clarifying it returns counts only, not job data. It makes the tool's narrow scope immediately recognizable.

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 routing instruction: 'Use ats_fetch_board when you want the jobs.' It also explains when to pass the optional company parameter and what a NAME_MISMATCH signifies, so an agent can decide between this tool and related ATS tools with clear context.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral detail: Workday pagination and performance trade-offs, how status codes (BOARD_EMPTY, SLUG_NOT_FOUND, etc.) are reported with detail instructions, the behavior of full_descriptions implying include_descriptions, and the rule about compensation only from structured data. It even warns against misinterpreting empty boards or 404s. This goes far beyond annotations and provides essential operational context.

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 long (12 parameters) but dense and efficiently structured. It leads with purpose, then parameter-by-parameter guidance, then result/error semantics. Each sentence earns its place; there is no fluff. The use of backticks for parameters and clear conceptual groups (e.g., filters vs. output shaping) makes it scannable despite its length.

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 description covers all necessary operational aspects: how to form slugs, query filtering, pagination, output format, status/error handling, performance considerations, and caveats about compensation and board-name availability. It even explains the distinction between filtering and keyword matching, and the implications of full descriptions. With an output schema present and rich annotations, nothing an agent needs to call this 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 0%, so the description must compensate. It does: platform values and their meaning (greenhouse/lever/ashby/workday), slug format (bare slug vs workday's three-part identity), company parameter for name-mismatch detection, title_filter behavior, updated_since semantics, keywords (non-filtering, adds keyword_hits), include_descriptions and full_descriptions trade-offs, response_format values, and the note on compensation. Every parameter is explained with usage nuance beyond the schema's bare types.

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+resource: "Read one company's job board from its ATS's public API, normalized." It explicitly contrasts with fetching a careers page for JavaScript-shell ATSs (Greenhouse, Lever, Ashby), which clearly differentiates it from generic page-fetch tools like http_request. This distinguishes it from siblings and states exactly what it does.

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 directly instructs "Use this instead of fetching a careers page" and explains why (those boards are JS shells). It also covers when to avoid it (platforms without board APIs like iCIMS/SuccessFactors/Taleo) and advises cross-checking those against aggregators. It implies single-board use vs. sweep tools by saying "one company's job board," giving clear context and alternatives.

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 mark this as read-only/idempotent/non-destructive, and the description adds substantial behavior beyond that: partial-failure semantics, status/detail per board, result ordering, state snapshots and diffs, pacing/timing, and response_format behavior. No contradiction with annotations 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?

The text is long, but each block earns its place given the batched/stateful complexity: roster format, failure behavior, state round-tripping, filtering caveats, and response_format. It is front-loaded with the core purpose and uses bold labels and an example to keep it scannable.

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 9-parameter, stateful sweep tool, the description covers invocation, defaults, per-board failure semantics, state diff mechanics, filter stability, batch composition, and output format. With an output schema present, it does not need to re-enumerate return fields, and nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description carries most of the semantic burden. It thoroughly explains boards (including the company/slug mismatch check), limit_per_board, include_descriptions, response_format, and previous_state, and points to ats_fetch_board for the filter arguments. A couple of parameters (include_compensation, updated_since) are only covered by that sibling reference rather than explicitly, which is a minor 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?

Opens with a specific verb and resource—'Sweep many job boards in one call'—then distinguishes itself from ats_fetch_board by scope ('batched', 'for breadth'). An agent can immediately tell this is the multi-board complement to the single-board 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?

Explicitly states when to use the sweep vs. going deep on one board ('Go deep on one board with ats_fetch_board'), and explains when to enable include_descriptions. It also calls out that full_descriptions is deliberately absent and that filters/state should be kept stable, giving concrete selection guidance.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, and it fully delivers: it states the fetch happens server-side, only public https URLs are fetched, no credentials are sent, up to five redirects are followed and checked, and the three statuses (LIVE, DEAD, UNVERIFIABLE) are precisely defined including edge cases like JS shells, bot blocks, timeouts, and redirect traps.

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 longer than average, but every sentence earns its place by adding operational detail needed for correct invocation. It is front-loaded with the core purpose, then progressively covers status semantics, parameter guidance, alternatives, and security behavior, with clear structure and no wasted words.

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 no annotations and no parameter descriptions in the schema, the description is remarkably complete: it explains the tool's network behavior, credentials, redirect policy, status outcomes, parameter semantics, and when to choose an alternative. The exact return shape is covered by the output schema, so nothing an agent needs to call this tool successfully 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 0%, so the description must compensate, and it does. It explains that url is fetched from the server side and must be public https, and it defines expected_title as a distinctive title fragment used to detect false positives from redirects, including the consequence if the title is missing (UNVERIFIABLE rather than LIVE).

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 opening sentence states a specific verb ('Check') and resource ('a job posting's canonical page is still live'), making the tool's function immediately clear. It is distinguished from siblings like ats_fetch_board by explicitly describing what this tool checks (a fetched HTML page) and when the ATS board API is preferred instead.

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 explicit when-to-use guidance: prefer ats_fetch_board with a title_filter for Greenhouse, Lever, Ashby, and Workday postings; use this tool for employer-hosted careers sites and aggregator-sourced leads. It also explains the expected_title parameter as a guard for redirect-to-listing sites, providing concrete decision logic for calling the tool correctly.

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

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

With no annotations, the description fully carries the behavioral burden and does so thoroughly: irreversible, no undo through the API, deletes the entire worksheet, and rejects deletion of the last remaining tab. These are exactly the warnings an agent needs before invoking a destructive operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action and irreversibility, then provides constraints, parameter semantics, and return behavior. Every sentence adds operational value with no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive two-parameter tool with no annotations, the description covers purpose, prerequisites, irreversible behavior, edge-case constraints, parameter guidance, and the return summary. The output schema covers return details, so nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description compensates for both parameters. It explains that sheet_id is the spreadsheet ID from its URL and is required, and that tab is the worksheet title, referencing list_sheet_tabs for lookup. This adds meaning well beyond the bare 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?

The description opens with a specific verb and resource: 'Delete a tab (worksheet) and all of its data.' It also clarifies the destructive scope ('removes the entire worksheet, not just its cells'), making the operation unmistakable among siblings like add_sheet_tab and rename_sheet_tab.

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 clear context for when to call: when an entire worksheet must be permanently removed, and it warns against calling if contents are needed ('confirm ... contents are expendable'). It also documents a hard exclusion (cannot delete the last tab) and points to list_sheet_tabs for obtaining the correct tab title, though it does not explicitly name an alternative tool for clearing cells or partial deletion.

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

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

With no annotations, the description carries the full disclosure burden. It usefully explains that a new paragraph is started, text is inserted after the current last paragraph, the document keeps formatting, and appended text is unstyled. It does not discuss permissions, errors, or length limits, but the core side effects of the operation are transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short, front-loaded with the primary action, and every sentence adds value: the operation, placement behavior, formatting result, and recommended use cases. There is no fluff or repetition of schema 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 simple two-parameter append operation with an output schema available, the description covers everything an agent needs: what it does, where the text goes, how formatting is affected, and when to use it. Missing auth details and error behavior are not critical for this straightforward 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 0%, so the description must compensate. It identifies text as 'plain text' and makes clear that document_id refers to a Google Doc. It does not state whether document_id should be an ID or URL, but the parameter names plus tool context are sufficient for this simple two-parameter tool.

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: 'Append plain text to the end of a Google Doc.' It also distinguishes itself from siblings like docs_replace_body by explicitly framing this as a non-destructive addition for logs, addenda, and updates that should not disturb existing content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear usage scenarios: 'Use this for logs, addenda, and updates that should not disturb what is already written.' It does not explicitly name alternatives or state when not to use it, but the use-case framing makes the decision context reasonably clear.

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?

Because no annotations are provided, the description carries the full behavioral burden. It usefully discloses the return shape, that paragraphs are joined with newlines, and that formatting is not represented. It does not explicitly state that the operation does not modify the document, but 'read' and the read-before-replace guidance make that non-mutating behavior strongly clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three tightly packed sentences: purpose, parameter clarification, then return and usage context. Every sentence earns its place and there is no redundant or filler content.

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 tool, the description covers input format, return contents, text formatting behavior, and the recommended call order relative to docs_replace_body. With an output schema also present, no essential information 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 0%, but the description fully compensates for the single parameter: document_id is the token in the Google Docs URL, with an exact URL template. This adds the practical meaning that a bare string schema cannot 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?

The first sentence states a specific verb and resource: 'Read a Google Doc's text content via the Docs API.' It further clarifies the output fields and implicitly separates this read operation from the docs_append_text and docs_replace_body siblings by positioning it as the read step.

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 an explicit workflow instruction: 'Read before docs_replace_body so the rewrite starts from what is actually there.' This tells the agent exactly when to call the tool and why, referencing a concrete sibling for the write step.

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

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

With no annotations provided, the description carries the full burden and fully delivers: it discloses formatting flattening, preservation of id/link/title/sharing/revision history, recoverability of the old body via Docs version history, and the replace-not-merge behavior. This gives the agent a complete picture of what is destroyed and what survives.

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 operation is front-loaded in the first sentence, and the overall length is appropriate for the complexity. Each subsequent clause adds distinct value — preservation, recoverability, workflow, and scope — but the information is delivered as one dense paragraph rather than cleanly structured guidance, which slightly reduces scannability.

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 description-level explanation. The definition covers the mutation's safety profile (formatting destroyed, identity and history preserved), the required read-first workflow, and the intended use case — everything an agent needs to correctly invoke a two-parameter replacement tool with zero annotations.

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. It does so for the text parameter by specifying it must be the complete new body in plain text, and the replace-not-merge clause further clarifies its semantics. document_id is never explicitly described, though it is trivially inferable from the tool name and purpose, making the compensation 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?

The opening sentence states a precise verb and resource: 'Replace a Google Doc's entire body with plain text.' The closing clause, 'this replaces, it does not merge,' explicitly differentiates it from docs_append_text and merge-style siblings, so an agent can distinguish this tool without inspecting sibling schemas.

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 names docs_read_text as a mandatory prerequisite ('Read with docs_read_text first and send the complete new body'), laying out a clear workflow. It also scopes applicability — 'for Docs that work as living text documents, not designed artifacts' — providing both a when-to-use and an implicit when-not-to-use signal.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It reveals idempotency (calling twice returns the same id), that only folders are created (never files), the error behavior when a segment matches two folders, and what the return value contains (leaf id, path, created list). This is a model of transparent behavior description, leaving no ambiguity about side effects or edge cases.

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 concise yet information-dense. Each paragraph earns its place: purpose, idempotency, path semantics, return values. The structure is logical and front-loaded with the core purpose, followed by crucial behavioral details. It avoids redundancy and is appropriately sized for the complexity of the 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?

For a tool with one parameter but complex behavior (idempotency, path resolution, ambiguity handling), the description covers everything an agent needs to call it correctly: input format, expected outcomes, error conditions, and return payload. The presence of an output schema further reduces the need to explain return structure in prose. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides zero description for the 'path' parameter (0% coverage). The description fully compensates by explaining the path format ('slash-separated from your My Drive root'), giving a concrete example ('Career/consulting/clients/acme'), and detailing how segments are handled (reuse, ambiguity error). This adds significant meaning beyond the raw schema, enabling correct usage.

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 precise statement of purpose: 'Create a folder path if it doesn't exist, and return the leaf's id.' This clearly names the verb (create), resource (folder path), and result (leaf id). It also introduces the 'idempotent mkdir -p' analogy, which instantly conveys the behavior. The scope ('only folders are created') further distinguishes it from file operations, making it easy to differentiate from siblings like drive_move_file or drive_update_file.

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 clearly implies when to use this tool: whenever an agent needs to ensure a folder path exists before proceeding. It explicitly mentions retry safety ('safe for an agent to retry'), which is a strong usage guideline. However, it does not explicitly name alternative tools or state when NOT to use it. The purpose is specific enough that an agent would not confuse it with other drive tools, but the lack of explicit exclusions keeps it from a perfect 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?

With no annotations, the description carries the full burden of behavioral disclosure. It thoroughly explains the effects: parent changes, id/name/contents preserved, links keep working, moving a folder moves its contents, and the create_destination flag behavior with a sensible default. It even explains the rationale behind the default. This is exceptionally transparent for a mutation tool.

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 structured into three clear paragraphs: the main action, the behavioral effects, and parameter details plus return. Every sentence adds value, but it is longer than strictly necessary. The information is well-organized and front-loaded, though it could be tightened without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a move operation with three parameters and an existing output schema, the description covers all essentials: what it does, what changes and what doesn't, how parameters work, the safety default, and the return value. No critical information is missing for an agent to call the tool 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 fully document each parameter. It does: 'file' is a Drive file id or path from My Drive root; 'destination_folder' is likewise an id or path and must resolve to a folder; 'create_destination' creates missing folders along the path and defaults to False. This adds substantial meaning beyond the schema's bare types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: 'Move a file or folder into a different Drive folder.' It specifies the verb (move), the resource (file or folder in Drive), and differentiates from siblings like rename or update by noting that id, name, and contents are untouched. This makes the tool's purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool (to change an item's parent) and explains important caveats (moving a folder moves everything under it, create_destination behavior). However, it does not explicitly name alternative tools or state when not to use it, leaving some inference to the agent. The guidance is strong 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?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It covers key side effects: links keep working, duplicate names are permitted but warned about, and path-based tool calls can fail due to ambiguity. It could mention permission requirements or irreversibility, but the core behavioral traits are well disclosed.

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 compact and front-loaded with the core action circles. Each sentence adds distinct value: the operation, the in-place guarantee and duplicate caveat, parameter semantics, and return value. No filler or 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?

For a two-parameter tool with no annotations gliding on a good output schema, this description is complete. It explains input formats, a critical failure mode, and return contents. An agent has everything needed to invoke the method 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 coverage is 0%, so the description must fully define the parameters, and it does. It specifies that 'file' is a Drive file id or a path from My Drive root, and 'new_name' must not contain path separators. This adds essential meaning that the bare string schema lacks.

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: 'Rename a Drive file or folder in place.' It immediately distinguishes itself from sibling tools like drive_move_file and drive_update_file by clarifying that the id and location are unchanged.

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 clearly implies when to use this tool: when the goal is renaming without changing location. It does not explicitly name sibling alternatives or state when not to use them, but 'in place' and 'id and location are unchanged' provide strong contextual guidance.

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

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

With no annotations provided, the description carries the full burden and excels. It discloses the dry-run default, the no-deletion guarantee, the built-in exclusion list that cannot be disabled, the abort-on-malformed-pattern behavior, and the refusal conditions (collisions and native conflicts). Every behavioral nuance an agent needs is explicitly stated.

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?

Though lengthy, the description is meticulously organized: a summary sentence, then behavior details, then parameter explanations, then safety guarantees. It uses bolded emphasis for critical warnings (dry run, no deletion) and bullet-like formatting for exclusions. Every sentence adds essential information without 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?

Given the tool's complexity (5 parameters, dry-run mode, exclusion patterns, collision handling), the description covers all operational aspects comprehensively. Since the context indicates an output schema exists, the description needn't document return values. The agent has everything needed to invoke it correctly and anticipate side effects.

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 fully explain each parameter, and it does. It clarifies local_path as a server-side directory, drive_folder as an id or path, create_destination's default, dry_run's boolean semantics, and exclude's glob syntax with directory-trailing-slash behavior. This goes well beyond the bare schema definitions.

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 precise verb-resource pair: 'Push a local folder tree into a Drive folder, creating or updating by name.' It is clearly distinct from sibling tools like drive_update_file (single file) or drive_ensure_folder_path (folder creation only). The scope 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?

The description explains when to use the tool (for syncing a directory tree) and provides important usage context like the dry-run default, but it does not explicitly name alternative tools or state when NOT to use it. The behavioral rules (collisions, native conflicts, exclusions) strongly imply the appropriate use cases. A dedicated 'use instead of X' statement would make it a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the action is destructive but recoverable for 30 days, that folder trashing cascades, and that the response echoes the resolved target for verification. It also explicitly states the absence of a hard-delete tool, making the tool's behavior fully transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action and uses compact, focused sentences. It efficiently covers recoverability, no hard-delete tool, folder cascade, and parameter semantics. A minor redundancy exists between 'recoverable, not deleted' and 'deliberately trash', but overall the structure is tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter destructive action, the description covers purpose, parameter format, behavioral consequences, and return values (resolved name, path, id, and restore instructions). The output schema exists, and the description adds the verification guidance. Nothing essential is missing for an agent to call this tool 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 schema only defines 'file' as a string with no description, so the description adds essential meaning by specifying it accepts either a Drive file id or a path from My Drive root. This directly compensates for the 0% schema coverage. It could be more precise about path syntax, but the provided semantics are adequate.

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 (move to trash) and resource (Drive file or folder), and explicitly distinguishes from permanent deletion by noting the item is recoverable. This clearly separates it from sibling tools like drive_move_file and drive_rename_file.

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 explains that this is the trash operation and that no hard-delete tool exists in the server, which informs when this tool should be used. It also warns that trashing a folder cascades to its contents. It does not explicitly mention alternative tools like drive_move_file, but the purpose and context are clear enough.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that the file keeps its link, location, sharing, that no duplicate is created, that previous content is retained as a revision (recoverable), that content replaces (not appends), and that it returns id, name, path, and modified_time. This is thorough and goes well beyond a basic statement of 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?

The description is well-structured, front-loading the core purpose and then logically expanding on behavior, parameters, and limitations. Every sentence adds value, with no redundant or filler content. The use of backticks and bold for emphasis aids readability without bloat.

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?

Despite having an output schema, the description still summarizes the return fields, which is helpful. It covers all necessary aspects: the operation, file identification, content semantics, MIME handling, edge cases (Google-native files, ambiguous paths), and revision safety. An agent has everything needed to invoke this tool correctly and understand its consequences.

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, and it does excellently. It explains 'file' as either an id or a path with an example, warns that ambiguous paths error, clarifies 'content' is the full replacement text, and details 'mime_type' override behavior. This fully demystifies all three parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Replace the contents of an existing Drive file, in place') and immediately distinguishes itself from siblings like drive_move_file and drive_rename_file by emphasizing the in-place, no-duplicate behavior. It clearly states what the tool does and what it is not.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly frames this as the missing Drive operation, indicating when to use it (to overwrite an existing file's contents) and provides a clear exclusion: it refuses Google-native files (Docs, Sheets, Slides). This gives an agent both a strong signal to use it for content replacement and a concrete when-not, though it does not name alternative tools by name.

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

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

With no annotations, the description carries the behavioral transparency burden. It does disclose two key behaviors: the response body is truncated, and json_body is sent as a JSON payload for POST/PUT/PATCH. However, it does not mention error handling, HTTP status codes, authentication/headers behavior, timeouts, or side effects of making arbitrary network requests.

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 only two sentences and every sentence adds value: the first defines the core behavior and truncation, the second states use cases and clarifies JSON body semantics. It is front-loaded with the most important 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?

Given that an output schema exists, the return shape may not need to be spelled out. Still, the input side is incomplete: headers, method constraints, error behavior, and authentication/security considerations are absent. The description is adequate for simple prototyping but leaves several important operational details to inference.

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 all four parameters. It only clarifies json_body's role for certain HTTP methods and implicitly assumes url is the endpoint. It does not explain headers, the allowed method values beyond the default GET, or how url should be formatted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action and resource: 'Make an HTTP request and return the response body (truncated).' It also hints at a narrower intended use ('quick API calls and connector prototyping'), which helps position the tool. It does not explicitly differentiate itself from sibling tools, but none of the siblings appear to be direct HTTP alternatives.

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 'Use for quick API calls and connector prototyping' gives clear when-to-use context. It does not state when not to use the tool or name alternatives, but the intended scope is explicit enough to guide an agent in typical cases.

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?

Since no annotations are provided, the description takes full responsibility. It transparently discloses side effects (shifting rows down, populating when values given), explains value_input_option behavior (parsing vs verbatim), and notes the return summary. It does not admit limitations like irreversibility or permissions, but for a spreadsheet insertion this is sufficient and consistent.

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?

Although longer than typical, every sentence adds value: purpose, differentiation, usage, parameter details, and return info. The structure front-loads the core action and then elaborates. There is zero redundancy or 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 5 parameters, no annotations, and an output schema, the description covers all necessary aspects: when to use, parameter semantics, edge cases (header row), and result summary. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by explaining every parameter: sheet_id from URL, tab from list_sheet_tabs, row_index as 1-based with shift semantics, values as optional list determining row count, and value_input_option behavior. This is exemplary compensation for a schema with no descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action ('Insert blank rows at a position, shifting existing rows down') and the resource (a spreadsheet sheet). It explicitly distinguishes itself from update_sheet_range by explaining what that sibling cannot do, leaving no ambiguity about its unique role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides concrete when-to-use guidance ('prepend at the top, or to insert into a sorted region') and explains the difference from update_sheet_range. Even gives a practical example (header row handling) and mentions the alternative tool by name, covering both use and exclusion contexts.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It does add useful context by specifying ordering ('most recently saved') and return content ('filename + first line'), but it does not mention side effects, permission requirements, pagination, or how the limit affects the result beyond the schema.

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, efficient sentence that front-loads the core behavior and includes the key return detail. There is no wasted text or repetition of schema 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?

The tool is simple, has one optional parameter, and an output schema exists, so the description does not need to explain return values at length. Still, it lacks guidance on the 'limit' parameter and any explicit usage boundary versus search_notes, making it adequate but not 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?

The description provides no additional meaning for the 'limit' parameter. Schema description coverage is 0%, so the description was expected to compensate; instead, the only parameter is left entirely to the schema, and the description adds no guidance on usage or constraints.

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 uses a clear verb ('List') with a specific resource ('notes') and defines the output scope as 'most recently saved' with 'filename + first line'. This distinguishes it from sibling tools like search_notes, which would be for query-based retrieval rather than a recent 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?

The description implies when to use it: when you need the most recently saved notes. However, it does not explicitly contrast it with search_notes or state when not to use it, leaving the routing decision partially to inference.

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

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

No annotations are provided, so the description carries the behavioral burden. It accurately describes a read-only listing operation and gives no indication of destructive side effects. It does not mention return ordering or error behavior, but the operation is simple and an output schema is present.

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 two concise sentences with no filler. The core purpose is front-loaded, and the parameter guidance is directly attached without unnecessary detail.

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 one-parameter list operation, the description provides the necessary context: what the tool returns conceptually, why it is used, and how to obtain the required parameter. The presence of an output schema covers return-value details.

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%, but the description fully compensates by explaining that sheet_id is the target spreadsheet's ID from its URL and is required. This gives the agent the exact meaning and source of the only 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?

The description clearly states a specific verb ('List') and resource ('tab (worksheet) names in a spreadsheet'), making the tool's purpose unambiguous. It does not explicitly name sibling tools for differentiation, but the list operation is clearly distinct from sibling tools like add_sheet_tab, rename_sheet_tab, and delete_sheet_tab.

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 provides clear context: use this tool to find the correct tab value before appending. It does not explicitly list exclusions or alternatives, but the usage intent is direct and actionable.

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

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

With no annotations, the description carries the full burden, and it does so thoroughly. It discloses that trailing empty rows/cells are omitted by the API, explains how to interpret len(values) to find the next free row, and details the three value_render_option behaviors. It also specifies the return object shape, covering the key behavioral aspects 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?

The description is appropriately sized for the complexity, front-loading the core purpose and then systematically explaining each parameter and the return semantics. Every sentence adds value; no redundancy or filler. It uses clear examples and structured explanations without being bloated.

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 read tool with a documented output format, the description is complete. It covers the return object with fields 'range' and 'values', explains the row/col structure, and addresses API quirks like omitted empty rows. It even provides a formula for the next free row, which is critical for the intended pre-write use case. No necessary information 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 0%, so the description must fully compensate, and it does. It explains sheet_id as the long token from the URL, range as A1 notation with examples (Sheet1 vs Sheet1!A1:E1), and value_render_option with the three enum-like values (FORMATTED_VALUE, UNFORMATTED_VALUE, FORMULA) and their meanings. This adds substantial meaning beyond the bare 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?

The description states a specific verb and resource ('Read cell values from a Google Sheet') and explicitly frames it as a pre-write step, distinguishing it from sibling write tools like append_sheet_row and update_sheet_range. It also clarifies the purpose of reading the header and data extent, making its role unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly instructs to read before writing and explains why, giving a clear when-to-use. It also details how to use range to read the whole used area or a specific subrange, and notes that sheet_id is required and should be confirmed per call. This effectively routes the agent to the correct usage.

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

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

With no annotations provided, the description carries full weight. It discloses the return value ("Returns a summary") and the important side effect that ranges referencing the old title must switch to new_title. It doesn't mention permissions or error behavior, but the mutating nature is clear from the verb.

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 compact and front-loaded, with the core action in the first sentence and each additional sentence earning its place by clarifying parameters or side effects. There is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter rename tool, the description is complete: it explains where inputs come from, how to find the current tab name, the uniqueness requirement, the return type, and the impact on formula references. The output schema covers the exact return shape.

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%, but the description defines every parameter: sheet_id as the spreadsheet ID from the URL, tab as the current tab title via list_sheet_tabs, and new_title as the replacement with a collision constraint. This goes far beyond the bare string-only 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?

The opening sentence states a specific verb and resource: "Rename an existing tab (worksheet)". This clearly differentiates the tool from siblings like add_sheet_tab, delete_sheet_tab, and list_sheet_tabs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: use this to rename an existing tab, and it points to list_sheet_tabs to obtain the current tab title. It also sets an explicit constraint that new_title must not collide with another existing tab, though it doesn't explicitly name excluded alternatives.

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 description is minimal, but it does disclose that it writes a file (a mutation) and returns the path, which is helpful. Annotations are absent, so the description carries the responsibility for transparency. It lacks details on overwriting behavior, formatting specifics, or error conditions, but given the tool's simplicity, this is acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences, the first stating the action, the second the return value. It front-loads the core purpose and adds minimal necessary detail. No fluff. Slight deduction for not structuring the return value info clearly, but overall 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?

Given the tool's simplicity (2 string params, no nested objects), the description covers the essential information: what it does, the format, and the return value. It doesn't detail how the title affects the file name or whether the body is raw markdown, but these are minor for a straightforward tool. With no annotations, it could add a bit more, but it's largely 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?

The schema has 0% description coverage (no descriptions for title or body), so the description must compensate. The description does not elaborate on the format of title or body translations to file name or content, which is a missed opportunity. However, the parameters are simple strings and their purpose is self-evident from the schema structure. The baseline is 3 for moderate 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?

The description clearly states the verb ('Save') and the resource ('a note as a markdown file'), and adds specificity by mentioning the local notes store and the file format. It is distinguishable from siblings like list_notes, search_notes, and drive operations that might superficially overlap.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for creating a note file but gives no explicit guidance on when to use this tool versus alternatives. There is no mention of exclusions, such as not for notes already existing (maybe list_notes/search_notes for retrieval). However, the context of a 'notes store' sets a clear context for note-related 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?

No annotations are provided, so the description carries the full burden. It states 'full-text search' and 'returns matching filenames' but does not disclose whether the operation is read-only, any limitations (e.g., case sensitivity, matching scope), or potential side effects. The behavioral details are minimal.

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 two short, direct sentences with zero waste. The action is front-loaded, and the return type is stated succinctly. It is appropriately concise.

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 tool with one parameter and an output schema, the description covers the core operation. However, it lacks usage guidance and behavioral transparency. It is adequate but not complete, especially given the absence of annotations.

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 schema has only a query parameter with no description (0% coverage), so the tool description must compensate. It does not explain what the query should contain, its format, or constraints beyond the parameter name. The description implies the query is the search term but provides no elaboration.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool performs full-text search across saved notes and returns matching filenames. It identifies the specific verb and resource, and the return value, which distinguishes it from siblings like list_notes that likely just enumerate notes without 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?

There is no guidance on when to use this tool versus alternatives. No mention of exclusions, prerequisites, or preferred contexts. An agent would have to infer when to use search_notes over list_notes or other tools.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly. It discloses idempotency via tag, deletion of previous tagged rules, preservation of hand-added rules, rule evaluation order, and the row range affected. This is exactly the kind of side-effect transparency needed for a mutation tool.

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 long but every sentence earns its place; the tool is genuinely complex. It is well-structured: purpose, use case, rule syntax, idempotency behavior, and parameter explanations are separated logically. The opening sentence front-loads the core function.

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 tool's complexity, the description is complete: it covers all five parameters, the rule schema, ordering semantics, idempotency, the range affected, and even the return value. The output schema exists for return details, so the description does not need to repeat those. An agent has enough to invoke this tool 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 fully compensate, and it does. It explains rules structure with formula/background/foreground semantics, gives a concrete formula example, describes tag behavior, and defines sheet_id, tab, and first_row defaults. Every parameter is given practical meaning.

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 opening line states a specific verb and resource: 'Colour whole rows by rule, as conditional formatting keyed on a formula.' It also distinguishes itself from cell-painting approaches, which separates it from siblings like update_sheet_range without needing to read 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?

The description gives an explicit use case: 'Use this to colour-code a tracker by a status column rather than painting cells once,' and explains why it is preferable. It also references list_sheet_tabs for resolving tab names, providing routing guidance to a sibling 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?

With no annotations, the description carries the full responsibility and does so well: it discloses overwriting behavior, non-shifting of other rows, value_input_option parsing semantics (USER_ENTERED vs RAW), and the return value. No required behavioral trait is hidden.

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 organized into purpose, usage scenarios, and parameter details. Every sentence adds value, and the most decision-relevant information (overwrite, no shifting, alternative tool) is front-loaded. It is detailed yet free of padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter tool with zero schema coverage and no annotations, the description covers purpose, when to use it, parameter semantics, examples, return value, and caveats about reading first. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description fully compensates. It explains sheet_id, range with A1 notation examples, values as a list of rows with a concrete example, and value_input_option with distinct USER_ENTERED and RAW semantics. This adds meaning far beyond the bare schema properties.

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: 'Write values into an explicit range, overwriting whatever is there.' This clearly distinguishes the tool from siblings like insert_sheet_rows and append_sheet_row by emphasizing deterministic placement rather than auto-detection or shifting.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit usage context: use for deterministic placement at a known row, edit existing rows, and avoid when inserting rows between existing ones — 'use insert_sheet_rows when you need to add a row between existing ones.' Also instructs to read the sheet and header first, giving actionable guidance.

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