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

Annotations indicate non-readonly and non-destructive behavior. The description adds that it returns a result message with comment ID but lacks details on side effects like notifications or permissions.

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 and well-structured: a brief summary, bulleted use cases, args list, and returns. It is front-loaded with essential info and no redundant text.

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 three-parameter tool with an output schema, the description covers purpose, usage, parameters, and return. It lacks error cases but is adequately 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?

With 0% schema coverage, the description compensates by explaining each parameter: document_id, text (supports markdown), and optional parent_comment_id for replies. It adds meaning beyond parameter names.

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 adds a comment or replies to an existing comment. It specifies verb, resource, and alternative use, distinguishing it from siblings like list_document_comments.

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 lists explicit use cases in a bulleted list, guiding when to use the tool. It does not specify when not to use, but the provided examples 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?

Beyond annotations (destructiveHint, idempotentHint), the description adds critical context: archived documents are removed from collections but remain searchable, and they don't appear in normal views. This explains the behavioral traits clearly.

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 with a purpose statement, a bullet list of behavioral effects, and a list of use cases. While slightly long, it is front-loaded and every sentence adds value. Could be slightly more concise but 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?

For a simple tool with one parameter and an output schema (indicated as present), the description covers purpose, behavior, usage, parameter, and return value. It is complete given 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?

The single parameter 'document_id' is described as 'The document ID to archive,' providing essential context beyond the schema's title. With 0% schema description coverage, this brief description compensates adequately.

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 'Archives a document to remove it from active use while preserving it,' using a specific verb and resource. It distinguishes from siblings like 'delete_document' (permanent removal) and 'unarchive_document' (reverse action), and 'batch_archive_documents' (bulk operation).

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 lists when to use this tool with four specific scenarios: removing outdated documents, cleaning up collections, preserving history, and temporarily hiding. It provides clear context compared to alternatives like deleting or unarchiving.

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?

Description adds context beyond annotations by stating the answer is AI-generated and includes sources. Annotations already declare readOnlyHint=true, so no contradiction. However, it does not clarify openWorldHint behavior (potential use of external knowledge).

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?

Well-structured with bullet points, separate Args and Returns sections. Every sentence is informative and earns its place. 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?

Covers purpose, usage, parameters, and return type. Could mention potential latency or limitations (e.g., token limits), but overall complete for a read-only query tool with good 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% (schema only has titles), but the description provides detailed explanations for all parameters (e.g., 'The natural language question to ask'). This adds significant value 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 that the tool queries document content using natural language questions, and provides specific use cases (e.g., find information across documents, get answers). This distinguishes it from sibling tools like search_document_content 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 bulleted list explicitly states when to use the tool (find info, get answers, extract insights). However, it does not explicitly say when not to use it or provide alternatives, which would strengthen 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?

The description adds behavioral context beyond annotations: documents are removed from collections but remain searchable, sequential processing with failure tolerance, and automatic rate limiting. Annotations already indicate destructive and idempotent behavior, so description complements well.

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 with an intro, behavioral notes, bullet points for use cases, recommended batch size, and parameter description. It is appropriately sized, though could be slightly more 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?

Given the tool's complexity (batch operation, potential failures), the description covers sequential processing, effects on visibility, recommended batch size, and output summary. It is adequate for an agent to 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?

With 0% schema description coverage, the description only provides minimal clarification for the single parameter 'document_ids: List of document IDs to archive.' This adds little beyond the schema's property title and type.

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 archives multiple documents in a single batch operation, using specific verbs and resource. It distinguishes from sibling tools like 'archive_document' and other batch 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?

Explicit use cases are listed (archive multiple outdated documents, clean up collections, batch hide without deleting) and recommended batch size is provided. It does not explicitly state when not to use, 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true), the description adds that operations are sequential and continue on failure, rate limiting is automatic, and recommends batch size. Adds useful context 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?

The description is moderately concise but includes an out-of-place note about Mermaid code fence syntax, which adds unnecessary detail. Could be streamlined.

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 single parameter with nested object, the description covers purpose, usage, behavior, and return summary. It lacks detail on failure behavior beyond 'continuing' but is generally complete for a well-annotated 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?

The description mentions 'documents: List of document specifications' but does not elaborate on sub-fields; the input schema already describes each property. The recommended batch size adds value, but overall parameter description is minimal.

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 'creates' and the resource 'multiple documents in a single batch operation'. It distinguishes from siblings like 'create_document' by specifying batch behavior.

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 lists explicit use cases (create multiple documents at once, bulk import, etc.) and implies that for single documents one should use alternatives. It provides good context, though could explicitly mention 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?

The description adds significant behavioral context beyond annotations: sequential processing, continued on errors, automatic rate limiting, 30-day trash retention for non-permanent, and immediate deletion for permanent. Annotations already indicate destructiveness and idempotency, but the description explains the nuances.

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 with paragraphs and bullet points, front-loading the main action. It is appropriately sized, though a bit verbose; still earns a solid 4.

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 only 2 parameters, a clear output schema mentioned, and annotations present, the description covers all aspects: purpose, usage, parameters, behavior, and return value. It is fully complete.

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

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

Input schema has 0% description coverage, but the description fully documents both parameters: document_ids as a list of IDs and permanent with its behavior (default false moves to trash for 30 days, true bypasses trash). This compensates completely.

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 deletes multiple documents, moving them to trash or permanently. It distinguishes from sibling tools like delete_document (singular) and batch_archive_documents (archive vs delete) by specifying the action and scope.

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 lists when to use this tool: removing multiple unwanted documents, cleaning up workspace, or permanently deleting sensitive information. While it lacks a direct 'when not to use' section, the sibling context implies alternatives, and the guidelines 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?

Annotations already indicate destructive (modification) and idempotent hints. Description adds sequential processing, error continuation, automatic rate limiting, and child document movement. Confirms that either collection_id or parent_document_id must be specified, adding useful constraint beyond the optional schema fields.

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 fairly concise given the complexity, with clear front-loaded purpose and use-case bullets. Slightly verbose with the 'IMPORTANT' note 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?

Covers purpose, usage, behavioral details, parameter semantics, and return value summary. Recommends batch size and notes automatic rate limiting. Lacks details on permissions, error scenarios, or behavior with invalid inputs, but adequate for a batch operation with output schema.

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

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

Schema coverage is 0%, so description must compensate. It explains document_ids as list of IDs, collection_id and parent_document_id as targets, with optionality. Adds the constraint that at least one of the optional parameters must be provided. This provides basic meaning but no format details or constraints on IDs.

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 'Moves multiple documents to a different collection or parent', providing a specific verb and resource. It distinguishes from siblings like move_document (single) and batch_archive_documents (archiving) by emphasizing batch move and reorganization.

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 lists use cases (reorganize multiple docs, move between collections in bulk, restructure hierarchies) and provides a recommended batch size. Lacks explicit when-not-to-use or direct alternatives, but context makes it clear for multiple documents.

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?

Beyond annotations (destructive, idempotent), the description adds sequential processing, error continuation ('continuing even if individual operations fail'), and automatic rate limiting. This provides useful behavioral 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 somewhat lengthy with a tangential note about Mermaid diagrams. While front-loaded with the main purpose, it contains some verbose formatting that could be tightened.

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 purpose, usage, behavior, and batch size. With an output schema present, return description is acceptable. However, it lacks details on failure handling specifics and does not explain the role of the 'append' parameter beyond what schema provides.

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%. The description only says 'List of update specifications' without adding detail. The schema itself has descriptions on each field, but the description text does not compensate for the lack of parameter documentation.

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 starts with a clear verb+resource: 'Updates multiple documents with different changes.' It distinguishes from siblings like 'update_document' (single) and batch operations for create/delete/archive.

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

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

Lists explicit use cases (batch edit titles/content, append) and provides a recommended batch size. However, it does not explicitly state when not to use it or mention alternatives like sequential single updates.

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 a non-readonly, non-destructive operation. The description adds that it returns a result message with a new collection ID. However, it does not disclose potential constraints like naming uniqueness, permissions, or side effects.

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 a clear introduction, bullet-pointed usage scenarios, and a structured parameter list. 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 simple tool with 3 parameters and output schema indicated, the description adequately covers the creation action and return value. It could hint at workspace context but is sufficient for the 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?

With 0% schema description coverage, the description explains each parameter: name (required), description (optional), and color (optional with hex example). This adds meaning beyond the raw schema, though it lacks details like length limits or validation.

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 creates a new collection for organizing documents, with specific use cases listed. It effectively distinguishes from siblings like delete_collection, update_collection, and list_collections.

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 scenarios for using the tool ('Use this tool when you need to:') with bullet points. It does not contrast with alternative tools or provide when-not-to-use guidance, but the positive guidance 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?

Annotations already indicate readOnlyHint=false (mutation) and idempotentHint=false. The description adds the Mermaid code fence detail and mentions the return format, but lacks information on authorization, error handling, or side effects. Adequate but not rich.

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 with paragraphs and bullet lists, but it is a bit verbose, including a tangential Mermaid note. However, every sentence adds value, and the argument descriptions are front-loaded.

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 parameter semantics well but is vague about the output, only stating a 'Result message with the new document ID.' With no output schema provided, this leaves ambiguity about the exact structure. Adequate for a creation tool but not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It does so thoroughly with an 'Args:' section that explains each parameter's purpose, including optionality, default behavior (e.g., publish default True), and allowed values (e.g., emoji for icon).

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 starts with a clear verb+resource: 'Creates a new document in a specified collection.' It distinguishes from siblings like update_document, delete_document, etc., and provides a list of use cases that reinforce its purpose.

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

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

The description explicitly lists five use cases for when to use the tool, helping agents decide. It does not explicitly state when not to use it or mention alternatives, but the context of sibling tools makes it 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?

Annotations already indicate destructiveHint=true. The description adds that the action is permanent and deletes all documents, which is valuable context. 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?

The description is concise with a clear structure: main verb, bullet points for use cases, and a warning. Every sentence contributes meaning, and it's front-loaded.

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, output schema exists), the description is complete. It explains the irreversible nature and the cascading effect on documents, which is sufficient for an agent to use it correctly.

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

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

With 0% schema description coverage, the tool description must compensate. It provides 'collection_id: The collection ID to delete', which adds a brief meaning beyond the schema's title and type, but is minimal.

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 deletes a collection and all its documents. It uses a specific verb ('removes') and resource ('collection'), and the purpose is distinct from siblings like delete_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 lists specific use cases (removing entire sections, obsolete collections, cleaning up) and provides a warning about irreversibility. It does not explicitly name sibling alternatives, but the 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?

Annotations already mark destructiveHint=true, but the description adds crucial context: default moves to trash with 30-day retention, permanent=True bypasses trash, and documents can be restored via restore_document. 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 well-structured with bullet points and clear sections. Every sentence adds value, and key information is front-loaded. Despite length, it remains concise and informative.

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?

Output schema exists, so return values need not be detailed. The description covers behavior, parameter semantics, and usage guidelines thoroughly. 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 description coverage is 0%, but the description fully explains both parameters: document_id as the document to delete, and permanent as the flag to bypass trash and delete without recovery. This adds significant value beyond the input 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 explicitly states the tool moves a document to trash or permanently deletes it. It distinguishes from sibling tools like restore_document, archive_document, etc., by explaining the two deletion modes and the recovery option.

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 a clear list of when to use the tool: removing unwanted documents, deleting obsolete content, cleaning workspace, or permanently removing sensitive info. It also mentions an alternative (restore_document) but does not explicitly state when not to use it.

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

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

Adds behavioral details beyond annotations: server-side editing, sequential edits, all-or-nothing, and save staging. No contradiction with destructiveHint=true. Does not describe all 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?

Well-structured with paragraphs. Slightly verbose but each sentence adds value. Front-loaded with core action.

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

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

Given sibling tools (read, update, archive), output schema, and annotations, the description covers editing behavior fully. Return value summary is 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?

Describes document_id, edits (list of DocumentEdit), and save with default. Explains old_string and new_string. Schema lacks descriptions for top-level props but $defs has some; description compensates.

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 edits a document via string-match replacement, specifying the verb, resource, and method. It distinguishes from siblings like update_document that likely modify metadata.

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 guidance on batching edits, uniqueness of old_string, sequential application, all-or-nothing failure, and save=false for staging. Lacks explicit when-not-to-use, but context with siblings makes it 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?

Annotations already indicate read-only, non-destructive, idempotent. The description adds critical behavioral context: the operation is asynchronous, may take time, returns status, and file access via UI. 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 concise (around 100 words), front-loaded with the core purpose, uses clear sectioning (IMPORTANT, bullet list, Args, Returns), and 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 that annotations cover safety, the description covers async behavior, format options, use cases, and return type. Output schema exists but the description sufficiently explains what the tool returns. No gaps identified.

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 has 0% description coverage for the only parameter 'format'. The description's argument section explicitly lists the allowed values ('outline-markdown', 'json', 'html'), adding meaning beyond the schema. A score of 4 reflects good compensation for low coverage.

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

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

The description clearly states the verb 'exports', the resource 'entire workspace content', and the outcome 'downloadable file'. It distinguishes this tool from siblings like export_collection and export_document by emphasizing the scope (entire workspace).

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 use cases in bullet points (backup, migration, archive, comprehensive export), which helps the agent decide when to use this tool versus partial exports. It implies not to use it for single-collection or single-document exports.

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 adds significant behavioral context beyond the annotations: it discloses that the export is asynchronous, may take time, returns operation status, and that the file is accessible via Outline's UI. Annotations already indicate readOnlyHint=true and idempotentHint=true, which are consistent with the description.

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 with a concise introductory sentence, an important async note, a bullet list of use cases, and clear args/returns sections. Every sentence adds value, and the information is front-loaded for quick understanding.

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 aspects: what the tool does, async behavior, parameter details, and returns information. Given the output schema exists (not shown but referenced), the description sufficiently explains the return value as operation info and file access. No gaps for an expert user.

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 clear meaning for both parameters: collection_id is the ID to export, and format specifies the export format ('outline-markdown', 'json', or 'html') with a default. Since the input schema has no descriptions (0% coverage), the description fully compensates and clarifies parameter roles and options.

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 exports all documents in a collection to a downloadable file, and lists specific use cases (backup, share, convert, archive). It distinguishes from sibling tools like export_document (single document) and export_all_collections (all collections), making its purpose specific and differentiated.

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

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

The description provides clear context for when to use the tool (backup, sharing, conversion, archiving) and notes the asynchronous nature. However, it does not explicitly mention when not to use it or compare directly to alternatives like export_document, which would further enhance guidance.

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

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

Annotations already mark it as read-only and idempotent; the description adds that it returns markdown text without additional formatting, providing useful behavioral 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 concise, well-structured with clear sections (use cases, args, returns), and 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 only one parameter, existing annotations, and an output schema, the description is complete—covering purpose, usage, and output format without gaps.

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

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

With 0% schema coverage, the description includes an 'Args' section explaining 'document_id', adding meaning beyond the schema's minimal 'title' field. It compensates adequately for a single 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 the tool exports a document as plain markdown text and lists specific use cases, distinguishing it from sibling tools like read_document or edit_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?

It explicitly lists when to use the tool (e.g., get clean markdown, extract content), but does not mention when not to use it or provide alternatives, though the context of siblings implies this.

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 explains the internal mechanism ('calls attachments.redirect, follows the redirect') and returns base64-encoded content. It mentions token limits for large files. Annotations already indicate read-only and idempotent, but description adds valuable behavioral context without contradiction.

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 with a clear opening, bullet points for usage, and a note with important caveats. Every sentence adds value and there is no redundancy.

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

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

Given the output schema exists, the description still details the return format with exact fields (Content-Type, Content-Length, Content-Base64) and handles edge cases like large files. It is fully adequate for an agent to understand behavior and results.

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

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

The only parameter 'attachment_id' receives a brief description ('The attachment UUID') which adds minimal meaning beyond the schema's type and title. With 0% schema description coverage, more detail on format or source would be helpful, but the parameter is simple and single, so 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 begins with 'Fetch attachment content and return it as base64,' a clear verb+resource. It distinguishes itself from sibling 'get_attachment_url' by explicitly recommending that alternative for large files.

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

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

The description lists specific use cases (read PDF, process images, etc.) and provides a clear note advising when to use 'get_attachment_url' instead for large files, offering explicit when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds operational context (calls attachments.redirect, returns final URL, allows clients to fetch themselves), which is valuable beyond the annotations.

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

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

The description is front-loaded with the purpose and is relatively concise. The bullet list for usage slightly repeats the purpose, but overall it is well-structured and not overly verbose.

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 low complexity (one parameter, no nested objects, output schema present), the description covers purpose, usage, parameter, and return value completely. No gaps remain.

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

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

The description explicitly documents the 'attachment_id' parameter as a UUID, adding semantic meaning beyond the schema's type and title. With 0% schema coverage, this compensates well.

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 resolves an attachment ID to a downloadable URL. It distinguishes from siblings like fetch_attachment by indicating the output is a URL for clients to fetch themselves.

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 lists specific use cases: getting a direct URL, sharing/referencing a URL, or letting another system fetch the file. It provides clear context but does not explicitly mention when not to use it or name 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 declare readOnlyHint and idempotentHint. Description adds return format but not deeper behavioral context like permissions or performance.

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?

Well-structured with purpose, bullet points, and arg/return sections. Slightly verbose but front-loaded.

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 essential aspects given simple tool: purpose, usage, and return value. Lacks detail on edge cases or limitations.

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

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

Schema description coverage is 0%, and the description only restates the parameter name without additional format 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 clearly states the tool retrieves hierarchical document structure, with specific use cases listed. It distinguishes from sibling tools which are primarily individual document or batch operations.

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

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

Explicitly lists when to use, but does not mention when not to use or provide alternatives. Context is clear enough for 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 states that the tool returns a 'formatted string with the comment content and metadata,' which adds behavioral context beyond the annotations (readOnlyHint, idempotentHint). There is 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 concise and well-structured: a one-sentence purpose, a bulleted list of use cases, and an args section. 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?

The description covers the tool's purpose, parameters, and return format. Given its simplicity (2 parameters, read-only), it is mostly complete. However, it does not mention error handling or behavior when the comment ID is invalid, which would be helpful for an 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?

With 0% schema description coverage, the description adds value by detailing both parameters: comment_id and include_anchor_text, explaining that the latter controls whether to include the referenced document text. This compensates for the lack of schema descriptions.

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

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

The description clearly states 'Retrieves a specific comment by its ID,' providing a specific verb and resource. It lists concrete use cases (view details, reference/quote, check content, find comment) that distinguish it from siblings like list_document_comments and add_comment.

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 outlines when to use the tool with a bulleted list of scenarios. While it does not mention when not to use it or name alternatives directly, the context is clear enough for an AI agent to select it appropriately.

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 and idempotentHint as true. The description adds the return type ('Formatted string listing all documents') which provides some behavioral context beyond annotations, but does not introduce additional traits like auth requirements or side effects.

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 (around 100 words) and well-structured with a header, bullet points, and clear sections for args and returns. Every sentence adds value with no redundancy.

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

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

Given the tool's simplicity (1 parameter, no nested objects, output schema exists), the description covers all essentials: purpose, usage context, parameter meaning, and return format. It is fully sufficient for an agent to 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?

The parameter 'document_id' is described as 'The document ID to find backlinks for', adding clear semantic meaning. Since schema coverage is 0%, this description compensates well, though it could be slightly more precise (e.g., note it's the document ID, not a URL).

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 'Finds all documents that link to a specific document', using a specific verb and resource. It lists concrete use cases (discover references, identify dependencies, find related documents, understand connections) which effectively distinguishes it from sibling tools like read_document or search_documents.

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 lists scenarios for use ('Use this tool when you need to:'). While it does not provide explicit negative guidance or alternatives, the context is clear and an agent can easily determine when to use this tool vs siblings.

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

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

Annotations already indicate readOnlyHint and idempotentHint, and the description adds valuable context: the matching algorithm (exact then partial), and that accuracy improves with more of the title. No contradictions 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 front-loaded with the main purpose and uses a clear structure with bullet points. However, it is somewhat wordy and could be more concise while retaining the same 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 the tool's simplicity (2 parameters, straightforward behavior) and the presence of annotations and an output schema, the description covers the necessary aspects: matching logic, use cases, and parameter roles. It does not detail the return format, but the output schema likely handles that.

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 compensates by explaining 'query' as a title for exact/partial search and 'collection_id' as an optional limiter. This adds meaning beyond the schema's type and requirement info, though no additional constraints or examples are given.

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

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

The description clearly states the tool's function: locating a document ID by searching for its title. It distinguishes from sibling tools by specifying that it returns an ID and uses exact-then-partial matching, which is unique among the sibling list.

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

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

The description lists specific use cases (e.g., when you only know the title, to get an ID for other operations). It does not explicitly state when not to use it or mention alternatives, but the provided use cases are clear and helpful.

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 and idempotentHint, so description doesn't need to repeat. It adds that output is formatted TOC with line numbers, which is helpful. 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 in a structured block with clear bullet points. Not overly long, but could be more concise. Sentences earn their 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?

With output schema present, return values are covered. Description provides usage context and links to other tools. Complete for a simple read-only 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?

Only one parameter (document_id) with 0% schema coverage. Description includes 'Args: document_id: The document ID', providing minimal but sufficient meaning for a straightforward 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?

Description clearly states it returns the heading structure as a table of contents with line numbers. It distinguishes from sibling tools like read_document and read_document_section by explaining usage for navigation and structure understanding.

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 lists when to use: understand structure, find sections, navigate by headings. Also suggests using line numbers with other tools. Lacks explicit when-not-to-use, but positive guidance 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?

Annotations already specify readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description's burden is lower. It adds that the return is a 'Formatted string containing list of archived documents,' providing minimal extra behavioral context beyond what annotations 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?

The description is concise, uses bullet points for clarity, and every sentence adds value. It is appropriately sized and front-loaded with the main purpose.

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 has no parameters, an output schema exists, and annotations are rich, the description is complete. It covers purpose, usage, and return type, leaving no critical gaps for agent invocation.

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

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

The tool has no parameters, and schema coverage is 100%. Since there are no parameters to explain, a baseline of 4 is appropriate; the description does not need to add parameter details.

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 'Displays all documents that have been archived.' It identifies the specific verb ('Displays') and resource ('documents that have been archived'), and effectively distinguishes this tool from siblings like list_trash or list_recently_updated_documents.

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 use cases: finding archived documents, reviewing archives, identifying documents for unarchiving, and checking archive status. It does not explicitly exclude scenarios or compare to alternatives, but the listed use cases offer clear guidance on when to employ the tool.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds behavioral context: it returns a formatted string with collection names, IDs, and descriptions, and it includes pagination handling instructions ('if response contains as many as limit, execute again with increased offset'). This goes well beyond the annotations.

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

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

The description is well-structured with a general statement, bulleted use cases, Args, Returns, and a pagination note. It is slightly verbose but 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 tool has only 2 parameters with defaults, readOnly and idempotent annotations, and an output schema (though not detailed), the description covers purpose, usage, parameters, return format, and pagination behavior. It is fully complete for an agent to use 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 carries the full burden. The Args section explicitly explains limit ('Maximum number of results to return') and offset ('Number of results to skip (pagination)'), adding meaning absent from 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 retrieves and displays all collections, listing specific use cases (see what exists, get IDs, explore knowledge base, find by name). This distinguishes it from sibling tools like create_collection, delete_collection, update_collection, etc.

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 a bulleted list of when to use the tool. It does not explicitly state when not to use it or mention alternatives, but the use cases are clear and relevant.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that it parses document content for attachment references and returns a list with context snippets, which is useful behavioral context beyond what annotations provide.

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

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

The description is concise and well-structured: a clear one-sentence summary, followed by a bulleted list of use cases, and then explicit Args/Returns sections. Every part contributes 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 tool's simplicity (one required parameter), the description fully covers its purpose, usage context, parameter, and return value. The presence of an output schema and clear when-to-use guidance makes 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?

The description defines the single parameter 'document_id' as 'The document ID to scan.' Since schema description coverage is 0%, this explanation adds necessary meaning beyond the bare schema, though it could include format or additional details.

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 'List attachment IDs referenced in a document.' It uses a specific verb (list) and resource (attachment IDs) and distinguishes itself from sibling tools via bullet points that mention related tools like get_attachment_url and fetch_attachment.

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 lists three use cases: discovering attachments, finding IDs for get_attachment_url or fetch_attachment, and auditing document references. This provides clear guidance on when to use the tool and references sibling tools, making it easy for an agent to decide.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds value by explaining pagination details (default 25 comments, need multiple calls) and that response indicates more comments available. 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?

Well-structured with sections (IMPORTANT, use cases, args, returns). Slightly verbose but each sentence adds value. No clutter.

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 4 parameters, no enums, and existence of output schema, the description covers pagination, return format (formatted string with author, date, anchor text), and use cases. Annotations cover safety. Complete for a read-only 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?

Input schema has 0% description coverage, but the description compensates by explaining all four parameters: document_id, include_anchor_text, limit, offset, including defaults and purpose. Fully compensates for lack of schema descriptions.

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

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

Clearly states it retrieves comments on a document with pagination support. Uses specific verb 'retrieves' and resource 'comments', distinguishing from siblings like 'get_comment' (singular) and 'add_comment' (create).

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 use cases: review feedback, see all comments, find specific comments, track collaboration. Mentions pagination behavior and need for multiple calls. However, does not explicitly contrast with alternatives or state 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 idempotentHint=true, so safety is conveyed. Description adds behavioral quirks: date_filter restrictions, status filter defaults, pagination details. 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?

Well-structured with sections (IMPORTANT, STATUS FILTER, PAGINATION, use cases). No fluff, but slightly verbose (200 words). Could be trimmed slightly.

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 simple list functionality and presence of an output schema (not shown but indicated), the description covers all key aspects: behavior, parameters, return format, use cases. Adequate for a non-complex 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 description carries full burden. It explains date_filter enum, collection_id optionality, status_filter values, limit/offset defaults. Good but could add more detail on return format beyond the short note.

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 'Lists documents ordered by most recent change (newest first).' Distinguishes from siblings like search_documents (keyword-based) and list_archived_documents.

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 lists use cases: 'Answer what documents changed recently / this week', 'Review recent activity', 'Catch up on edits'. Implicitly excludes keyword search scenarios.

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 read-only, idempotent. Description adds return format (formatted string) but overlaps with output schema. No additional behavioral 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?

Very concise with bullet points for use cases. 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?

Simple tool with no params, good annotations, and output schema. Description covers all needed context.

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

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

No parameters - baseline 4. Description adds nothing needed beyond 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?

Clearly states it displays documents in trash, with specific use cases. Distinguishes from sibling tools like list_archived_documents.

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 scenarios (find deleted, review pending deletion, etc.). No explicit exclusion 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?

Beyond annotations (destructiveHint=true), the description adds critical context that all child documents move along, maintaining hierarchy. This addresses a key behavioral nuance not captured by annotations alone.

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

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

The description is well-structured with sections and bullet points, but slightly verbose. It front-loads the main action and important note, then lists use cases and parameters. Minor improvement could tighten wording.

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 (3 parameters, no nested objects, output schema exists), the description covers behavior, constraints, use cases, and parameter semantics thoroughly. No gaps identified.

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 explains each parameter's role, including the nuance that collection_id or parent_document_id must be specified. This compensates entirely for the missing schema descriptions.

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

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

The description clearly states it relocates a document to a different collection or parent document. It lists specific use cases like reorganizing hierarchy, which distinguishes it from siblings like archive_document or delete_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?

It provides explicit when to use scenarios (reorganize, move to collection, change parent, restructure) and specifies the constraint of choosing collection_id or parent_document_id. However, it does not explicitly mention when not to use or alternatives like batch_move_documents for multiple documents.

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 read-only and idempotent. Description adds that output includes line numbers and metadata header when paginated, and full document format for backward compatibility when offset and limit are default. No contradiction.

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 sections and front-loaded purpose. Slightly verbose with Returns line stating the obvious, but overall concise and clear.

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 3 params (1 required), output schema, and annotations, description covers behavior, parameters, and return format. Could mention error handling or edge cases, but sufficient for a read 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 has 0% description coverage. Description provides detailed Args: document_id (ID to retrieve), offset (0-based, non-negative, default 0), limit (number of lines, 0 means all, non-negative, default 0). Adds significant meaning beyond schema 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?

Description clearly states it retrieves and displays document content, optionally paginated. Distinguishes from siblings like read_document_section by specifying line range vs section focus.

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 lists use cases: access complete content, read specific range, review details, quote/reference. No direct mention of when not to use, but context with sibling tools makes it 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds important behavioral details: case-insensitive matching, end boundary condition (next heading of same/higher level), inclusion of nested subsections, and return of line numbers. No contradiction.

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: core function, detailed behavior, use cases, parameter descriptions, and return value. Every sentence adds information; no fluff. Front-loaded with essential purpose.

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 (2 parameters, clear behavior) and presence of an output schema (covering return values), the description covers all necessary aspects. It omits error conditions but is sufficiently complete for a read-only tool with 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 provides essential meaning for both parameters: document_id as 'The document ID' and heading with an example of substring matching. This adds value beyond the schema's title fields, though it remains somewhat terse.

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 reads a specific document section by heading match, with specific matching behavior (case-insensitive substring, returns from matched heading to next same/higher-level heading including nested subsections). This distinguishes it from siblings like read_document (entire document) and get_document_toc (just headings).

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 lists three use cases for the tool, giving clear guidance on when to use it. However, it does not explicitly state when not to use it or mention alternatives, though the use cases implicitly differentiate from read_document.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, indicating a safe, non-destructive operation. The description adds context about the 30-day recovery window and returns a confirmation, 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?

The description is concise with bulleted use cases and structured Args/Returns sections. Every 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?

For a simple tool with one required parameter, no nested objects, and an output schema, the description fully explains when to use it, what it does, and the outcome. It covers the essential context without gaps.

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

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

The schema has 0% description coverage for the single parameter 'document_id'. The description only repeats 'The document ID to restore' without adding format, constraints, or how to obtain it. This minimally compensates for the missing schema descriptions.

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

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

The description clearly states the tool recovers a document from trash to active status, using specific verb 'Recovers' and resource 'document'. It distinguishes from sibling tools like archive, delete, or move, as no other tool focuses on trash restoration.

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 lists clear use cases: retrieve accidentally deleted, restore from trash, recover within 30 days, access previously trashed content. While it doesn't explicitly state when not to use or mention alternatives, the context is sufficiently clear for an agent to decide.

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 readOnlyHint and idempotentHint. The description adds valuable behavioral details: case-insensitive matching, 0-based line numbers, and context_lines default/constraint. This goes beyond annotations without contradiction.

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: purpose sentence, bullet list for usage, behavioral details, parameter list. Every sentence adds value, and the most important information is front-loaded. No unnecessary 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 simplicity (3 params, no nested objects) and presence of an output schema, the description covers all essential aspects: purpose, usage, matching behavior, return format. It is fully sufficient for an agent to 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 0%, so description carries full burden. It explains all three parameters: document_id, query, context_lines (with default and constraint). It does not specify query format (exact vs regex) but provides sufficient meaning for typical use.

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 searches within a document for text (grep-style), returns matches with line numbers and context. It distinguishes from siblings like read_document (full read) and edit_document (edit) by explicitly referencing them as use cases for building arguments.

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 when-to-use scenarios: locate specific text without reading full document, and find line numbers to build edit_document old_string or read_document offsets. It does not state when not to use, but the context is clear enough for an agent to decide.

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 readOnlyHint and idempotentHint. Description adds details on full-text search, ranking, snippet generation, pagination, and status filtering, significantly extending 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?

Well-organized with clear sections and front-loaded purpose. Slightly verbose in use cases, but 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?

Comprehensive coverage of search behavior, pagination, status filtering, and all parameters. Output schema is implied via return description. Sufficient for effective use.

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 includes an Args section that fully explains all five parameters, their defaults, allowed values, and 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?

Clearly states search for documents with keywords across knowledge base. Specific verb and resource, but does not explicitly differentiate from sibling 'search_document_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?

Lists multiple scenarios for usage (find specific terms, locate info across documents, etc.) and describes pagination and status filter defaults. Does not specify when not to use or compare to 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 aligns with annotations (idempotentHint=true, not destructive) and adds details like making content visible in collections again, which goes beyond what annotations provide. 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?

The description begins with a clear main sentence, followed by bullet points and structured Args/Returns. It is appropriately sized for a simple tool, though the bullet points add some verbosity.

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 (one parameter, clear purpose) and the presence of an output schema (not shown but referenced), the description adequately covers behavior and context. It explains the effect on visibility without missing crucial 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?

The schema has 0% description coverage for parameters. The description's Args section provides only a basic 'The document ID to unarchive', which adds minimal meaning beyond the parameter name. For one required parameter, this is acceptable but not enriching.

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 ('restores a previously archived document to active status') and the resource ('document'), with a specific verb and object. It distinguishes from siblings like 'archive_document' by focusing on the reverse operation.

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 use cases ('Use this tool when you need to: restore archived documents...') and covers common scenarios. It does not list when not to use or compare directly with siblings like 'restore_document', but the context is 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?

Annotations already indicate destructiveHint=true, so description's 'Modifies' adds no new behavioral insight. It adds context about what properties can be changed but lacks details on side effects or authorization.

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?

Concise one-sentence summary, followed by bullet list of use cases, then args, then returns. Front-loaded with purpose, no redundant info.

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 purpose, when to use, all parameters, and return value. Lacks validation details (e.g., hex format for color) and error conditions, but adequate for a simple update tool.

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

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

Schema coverage is 0%, but description explains each parameter: collection_id, name, description, color (with hex example). Fully compensates for lack of schema descriptions.

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

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

Description clearly states 'Modifies an existing collection's properties' with specific use cases (rename, update description, change color coding, refresh metadata). Distinguishes from sibling tools like create_collection, delete_collection.

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 lists when to use with bullet points (rename, update description, change color, refresh metadata). No mention of when not to use, but context from siblings 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 indicate destructiveHint=true, and the description adds that it replaces content rather than appending. It also explains the append parameter. No contradictions. It doesn't detail further side effects, but the annotations handle safety profile adequately.

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?

Well-structured with a summary, warning, bullet list, and parameter descriptions. Front-loaded with the core action. No unnecessary sentences; each part 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?

Comprehensive: covers all parameters, behavior, usage guidance, and a rendering note. Output schema exists, so the vague return mention is acceptable. Adequate for a tool with 6 params and 1 required.

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's Args section fully explains each parameter's purpose, default behavior (e.g., None keeps existing), and special cases (e.g., icon empty string removes). Adds significant value.

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 modifies an existing document's title or content, and lists specific use cases. It distinguishes from the sibling tool 'edit_document' by noting that this tool replaces content rather than making partial 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?

Explicit guidance is provided: for partial edits, prefer 'edit_document'. It lists when to use this tool (replace entire content, change title, append, convert template) and includes a note about Mermaid diagram syntax.

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