Revise

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

Annotations are minimal (readOnlyHint=false, destructiveHint=false), but the description fully discloses behavioral traits: document is private, deleted after 7 days if unclaimed, no account required, and how tokens are used for authorization. No contradictions.

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 concise (4 sentences) with front-loaded purpose and return values. Every sentence provides essential information without redundancy. Excellent structure for quick comprehension.

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 adequately explains return values and their usage. It covers document creation, lifecycle, and authorization. Missing details on error handling or rate limits, but these are less critical for a creation tool. Sufficiently complete for an AI agent.

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

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

Schema description coverage is 100%, so the schema already documents parameters. The description adds marginal value: for 'created_by' it suggests using a name (e.g., 'Codex') and marks as recommended; for 'content_markdown' it repeats 'Initial content as markdown'. This adds minor context but does not significantly surpass the schema 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?

The description clearly states the verb 'Create', the resource 'Revise document', and distinguishes from siblings by emphasizing 'without a Revise account' and 'seeded with markdown'. It also explains the return values and their purpose, making the tool's 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?

The description provides explicit guidance on how to use the returned url and edit_token, and explains the lifecycle (private, deleted after 7 days if unclaimed). It implies when to use this tool (when user has no account) vs. other tools (for existing documents). Lacks explicit 'do not use when' conditions, but context is 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?

The description reveals that edits can be tracked changes (suggest mode) or direct revisions (apply mode), and that direct edits are recorded in revision history, aligning with the destructiveHint=true annotation. It also explains how to obtain block IDs from read_document, adding context beyond annotations.

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

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

The description is a single paragraph that covers essential information efficiently. It front-loads the purpose, then explains modes, and ends with a practical tip. It is concise but could be more structured with bullet points for even easier 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?

Given the complexity of multiple edit types (replace, insert_markdown, insert_html, delete_block) and the presence of an output schema, the description provides complete context. It explains each edit type implicitly through the concept of 'targeted edits' and the mode behavior.

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

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

Schema coverage is 100%, but the description adds value by explaining the mode behavior in detail and providing guidance on obtaining block_ids. The description enriches understanding without redundancy.

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 applies targeted edits using Markdown or HTML content, and specifically mentions actions like replace, insert, and delete. It distinguishes itself from siblings like replace_document_content by focusing on targeted block-level edits.

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 explicit guidance on when to use 'suggest' vs 'apply' modes based on document length (20+ words vs under 20 words). It also tells how to explicitly force 'apply' on substantial documents. However, it does not mention when to use alternative sibling tools like replace_document_content.

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 indicate readOnlyHint=true and destructiveHint=false. The description adds crucial behavioral context: text formats are returned inline, while binary formats are hosted at a temporary download URL with a 24h expiry. No contradictions.

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 wasted words. The most important distinction (inline vs. URL) is front-loaded. Every sentence adds value.

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 there is an output schema, the description does not need to detail the response. It covers the key aspects: supported formats, how each is returned, and the expiration of download URLs. It is complete for the tool's complexity.

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% (only 'id' has a description). The description adds meaning to the 'format' parameter by explaining the inline vs. URL behavior, compensating for the missing schema description. It does not add new info about 'id' but that is already clear.

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 ('Export') and resource ('document'), lists supported formats, and distinguishes behavior between text and binary formats. It clearly differentiates from sibling tools like import_document or read_document.

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 states the tool's purpose (exporting a document) and implicitly guides when to use alternatives (e.g., read_document for reading, create_document for creating). It does not explicitly state when not to use, but the context is sufficient for an 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=true and destructiveHint=false, providing safety clarity. The description adds behavioral context by specifying the exact metadata fields returned, enhancing transparency without contradicting 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 redundancy. Every word serves the purpose of conveying the tool's function and output.

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 (1 parameter, rich annotations, and existence of an output schema), the description fully covers what an agent needs: it identifies the resource, the nature of the operation, and the type of information returned.

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

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

Schema coverage is 100% with a single 'id' parameter described as 'Document ID'. The description adds no further meaning to the parameter beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool retrieves a document's metadata, listing specific fields (title, sharing state, URLs, timestamps, word count). This distinctively separates it from siblings like read_document (content) and get_document_outline (structure).

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 when metadata is needed, but lacks explicit guidance on when to use this tool versus alternatives (e.g., read_document for content, get_document_outline for structure). No exclusions or context for when not to use.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by specifying the output contains 'block ids and per-section word counts' and characterizes it as a 'cheap' operation. This goes beyond the annotations, though it could mention more about performance 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?

The description consists of two concise sentences with no wasted words. The first sentence front-loads the core purpose, and the second adds context. 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?

The tool has an output schema (though not detailed in the prompt), and the description adequately summarizes what is returned: headings, block ids, and word counts. For a simple outline retrieval, this provides sufficient context for the agent to understand the tool's scope.

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

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

Schema description coverage is 100% for the single parameter 'id'. The description does not add any additional meaning beyond what the schema provides. Per the rubric, baseline is 3 when coverage is high, and there is no extra semantic value in the description.

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 ('Get') and clearly defines the resource ('document's heading outline with block ids and per-section word counts'). It distinguishes from siblings like read_document by explicitly framing it as a cheap orientation tool, making the purpose unmistakable.

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 guides the agent on when to use this tool: 'Cheap way to orient in a long document before reading specific sections'. It implies that for full content reading, one would use read_document. However, it does not explicitly state when not to use it or list alternative tools, so it loses one 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 indicate read-only and non-destructive. The description adds key behavioral traits: returns blocks with ids, states (accepted/projected), and the baseline advancement behavior.

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 concise, well-structured, and front-loaded with purpose. Every sentence adds value 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 output schema exists, description adequately covers return values and behavioral nuances. The simple param set and clear annotations make it 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 coverage is 100% with clear parameter description. Description adds no extra meaning beyond what schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb ('See') and resource ('recent changes') with a specific scope since the user last looked. It clearly distinguishes from siblings like read_document or get_document_info by focusing on changes.

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 ('catching up before continuing work'), explains the baseline mechanism, and implies not for other purposes. No exclusions needed.

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?

Discloses key behaviors beyond annotations: server fetches URL (not inline), document private and deleted after 7 days if unclaimed, and that the edit_token is for future edits. No contradiction with 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?

Four sentences, no redundant words, front-loaded with core action, each sentence adds essential information. Example of excellent conciseness.

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?

Covers input (URL, options), process (server fetch), output (id, url, edit_token), and lifecycle (7-day deletion, claiming). No gaps given the tool's complexity and available metadata.

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?

Though schema has 100% coverage, the description adds value by explaining that URL must be public http(s), filename override selects converter, and created_by is recommended for user visibility. Returns are also explained.

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 it creates a Revise document from a public HTTP(S) URL, lists supported formats, and contrasts with upload_document for local files, making the purpose unambiguous and distinct from sibling tools.

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 tells when to use this tool (public URL), when not to (local files), and names the alternative (upload_document). Also notes unsupported formats (PDFs/images), providing clear usage boundaries.

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?

Discloses that on substantial documents it lands as a pending tracked change by default, similar to edit_document. It explains the relationship between footnote body and reference. No contradiction with annotations (idempotentHint=true is 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?

It is concise with three well-structured sentences, front-loading the core purpose. Every sentence adds value 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 presence of an output schema (context signals indicate yes), the description does not need to explain return values. It sufficiently covers behavioral aspects, parameter context, and inter-tool relationships.

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

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

Schema coverage is 100%, so baseline 3. The description adds meaning by explaining that 'find' is anchor text after which the reference is inserted, and that empty string appends at end. Also clarifies 'kind' (footnote vs endnote) and 'mode' (apply vs suggest) beyond enum values.

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 it inserts a footnote with a numbered superscript reference and footnote body. It distinguishes itself from sibling tools like edit_document and implies its specific role among document editing tools.

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

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

It provides context for when to use (inserting footnotes) and mentions that footnote bodies can be edited/removed with normal editing tools, with a note about removal symmetry. It lacks explicit 'when not to use' but is sufficient.

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. The description adds behavioral details: how view affects pending suggestion projection, and how format and with_block_ids modify the output. No contradictions.

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

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

Three dense, front-loaded sentences with no redundancy. Every sentence adds unique value: purpose, format/block ids usage, and view behavior. Efficient and easy to parse.

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 presence of output schema and annotations, the description adequately covers usage context and parameter behavior. It implicitly addresses the tool's role among siblings (e.g., editing workflow). Minor omission: no explicit mention of the response being the full document content, but output schema likely covers this.

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 covers 75% of parameters with descriptions. The description adds context for format (explaining default and use cases) and with_block_ids (linking to edit_document), going beyond schema details. View parameter is similarly clarified.

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 'Read a Revise document's content' with a specific verb and resource. It distinguishes from siblings like get_document_info by focusing on content retrieval, though it doesn't explicitly list all alternative tools.

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 clear guidance on when to use each format (markdown for editing, text for plain text) and how with_block_ids enables use with edit_document. Also explains view parameter for tracked suggestions. Lacks explicit 'when not to use' but sufficient for parameter selection.

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 does not contradict annotations (idempotentHint true, destructiveHint false) but adds minimal extra context. It merely restates the action without elaborating on side effects or behavior beyond what annotations already convey.

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, well-formed sentence communicates the tool's purpose with zero wasted words. It is front-loaded and easy to parse.

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 params, full schema coverage, annotations, and output schema present), the description is sufficient. It could optionally mention idempotency or return value, but annotations and output schema cover those aspects.

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

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

Schema description coverage is 100%, so the input schema already explains both parameters adequately. The tool description adds no new meaning 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?

The description clearly states the action ('Change') and the specific resource ('a document's title'), distinguishing it from sibling tools like edit_document or export_document. It is precise and 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?

No guidance is provided on when to use this tool versus alternatives such as edit_document or replace_document_content. The agent receives no context about prerequisites or exclusions.

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. Description adds context that existing content remains recoverable via revision history, which is 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?

Two sentences, no filler. Front-loaded with the core function, then constraint and alternative. Every sentence adds value.

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 simplicity of the tool (2 params, no output schema needed), the description covers the core behavior, destructive nature, and recoverability. Could mention markdown format constraints but sufficient.

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

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

Schema description coverage is 100%. Description adds 'new markdown' for content_markdown, but it's largely redundant with the schema descriptions. Baseline 3 is appropriate.

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

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

Description clearly states it replaces the entire document content with new markdown. It distinguishes from sibling edit_document by indicating that tool is for targeted changes.

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 (replace entire content) and when not (prefer edit_document for targeted changes). Also mentions recoverability via revision history.

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 provide idempotentHint=true and destructiveHint=false. The description adds that it only affects the agent's own suggestions, covers the whole document by default, and can be limited to specific blocks. It does not contradict annotations, though more detail on error conditions could improve transparency.

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 main sentences plus parenthetical clarifications. It front-loads the key purpose and usage context, with no extraneous 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 the tool's moderate complexity (4 parameters, 2 enums, output schema exists), the description covers purpose, usage, scope, and differentiation from sibling tools, making it complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, and the description adds valuable context beyond the schema: it explains default behavior (whole document), the effect of block_ids, and clarifies the action parameter meanings.

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 accepts or rejects tracked-change suggestions made by the agent, specifying the verb 'accept/reject' and the resource 'your own suggestions'. It distinguishes from siblings like edit_document by noting that this tool is for suggestions left in 'suggest' mode.

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 guidance is provided: use when the user approves ('lgtm'/'looks good') or asks to withdraw. It also explains when not to use (if edits were already applied via edit_document in 'apply' mode), helping the agent choose 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description correctly adds value by explaining the return format (markdown with anchors) and case-insensitivity. It does not contradict annotations.

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

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

Two concise sentences, front-loaded with the core purpose. No unnecessary words. Every sentence adds value.

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 presence of an output schema (context signal), the description does not need to explain return values. It covers key behavioral aspects (anchors, context, case-insensitivity) and is complete for a search tool with three 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 100%, so the schema describes parameters. The description adds useful context: 'case-insensitive' for query, and 'neighboring blocks for context' aligns with context_blocks parameter. It goes 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?

The description clearly states the tool's action (find matches), the resource (one document), and the output format (markdown with block anchors and context). It distinguishes itself from sibling tools like read_document or get_document_outline by focusing on search within a document.

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 (search within a document) and mentions the output is usable with edit_document. It does not explicitly state when not to use it, but the context from sibling tools fills that gap. Minor improvement could be to mention it's for targeted search, not full content retrieval.

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 indicate idempotentHint=true and destructiveHint=false. The description adds that length values use explicit units but does not disclose other behavioral traits such as whether changes are applied incrementally or override existing settings. The description adds minimal transparency beyond annotations.

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

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

Two sentences efficiently cover the tool's scope and a crucial detail about unit formatting. No extraneous information; every sentence adds value.

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 complexity (15 parameters, 1 required) and the presence of an output schema, the description provides a sufficient high-level overview. While it does not detail every parameter, the schema descriptions fill gaps, and the description gives the essential scope.

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 53% (low), but the description adds meaning by naming key parameters and clarifying that length values are strings with explicit units (e.g., '1in', '2.54cm'). This compensates for some undocumented schema fields, though not all parameters (e.g., note_mode, page_number_start) are mentioned.

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

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

The description clearly states the tool's purpose: 'Set a document's page layout' and lists all supported aspects (page size, orientation, margins, etc.). It uses a specific verb ('Set') and resource ('document's page layout'), differentiating it from sibling tools like 'edit_document' or 'create_document'.

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 the tool is used for page layout modifications but provides no explicit guidance on when to use it versus alternatives. No when-not or exclusion criteria are mentioned, leaving the agent to infer from 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?

Despite sparse annotations, the description comprehensively discloses behavioral traits: file is uploaded without bytes in context, returns one-time upload_url and curl command, response contains url and edit_token, document is private and deleted after 7 days if unclaimed. No contradiction with annotations.

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

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

The description is slightly long but well-structured, front-loaded with purpose, and each sentence provides essential information without redundancy. Could be marginally tighter but overall effective.

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 complexity of a no-account file upload tool, the description covers all necessary aspects: purpose, file type constraints, alternative workflow, output fields, and document lifecycle. The presence of an output schema reduces the need to describe return values.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by explaining that the filename extension selects the converter and that created_by is recommended for user visibility, going beyond the 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?

Clearly states it creates a Revise document from a local file, specifies supported formats (docx, md, txt, html) and explicitly excludes PDFs/images. Also differentiates from the sibling tool import_document.

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 when-to-use (local files) and when-not-to-use (public URLs or tiny inline files) with a direct reference to the alternative tool import_document. Also outlines the workflow: returns upload_url and curl command.

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