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

Annotations indicate mutation, and description adds return value context and markdown support, 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 short summary, bullet use cases, and labeled sections for args and returns, 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?

The description covers purpose, usage, parameters, and return value. No output schema provided, but return info is included. Sufficient for this simple tool.

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

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

With 0% schema description coverage, the description fully explains each parameter's purpose and constraints, including optional parent for replies.

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 the tool adds a comment or replies, distinguishing from sibling tools 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?

Provides explicit use cases (feedback, questions, replies, collaboration) but does not mention when not to use or 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 explains key behavioral traits beyond annotations: documents are removed from collections but remain searchable and can be found via search or the archive list. This adds significant context to the destructiveHint annotation, and 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 well-structured with a clear summary, an important note in bold, bullet points for usage, and a separate Args section. It is concise with no wasted words, fitting the tool's simplicity.

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, no nested objects), the description covers all necessary aspects: purpose, behavior, usage guidelines, parameters, and return value. The presence of an output schema (not shown) further supports completeness.

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

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

There is only one parameter (document_id), and the description provides a brief yet meaningful explanation ('The document ID to archive'). Given 0% schema coverage, this description compensates adequately, though it could include a format or example.

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

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

The description uses a specific verb-resource combination ('Archives a document') and clearly distinguishes it from siblings like delete_document by emphasizing preservation and the fact that documents remain searchable but are removed from active use.

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

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

The description lists explicit use cases (e.g., removing outdated documents, cleaning up collections) and implies when not to use it (e.g., if deletion or permanent removal is intended). It does not explicitly name alternative tools, but the context from siblings 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=true and openWorldHint=true. The description adds that the tool provides AI-generated answers with sources, consistent with a read-only information retrieval operation. It does not discuss potential limitations like latency or hallucination, but annotations cover the behavioral traits 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?

The description is concise and well-structured: a brief purpose statement, bullet-pointed use cases, an Args section, and a Returns note. 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 tool's complexity (simple query interface with optional filters, output schema present), the description covers purpose, use cases, parameters, and return format. It is complete for an AI agent to select and invoke the tool correctly.

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

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

Despite 0% schema description coverage (property descriptions missing in schema), the tool description includes a dedicated 'Args' section that explains each parameter: question as the natural language query, collection_id and document_id as optional filters. This adds clear meaning beyond the schema's type and required fields.

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

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

The description clearly states the tool queries document content using natural language questions, with specific examples (e.g., 'What is our vacation policy?'). This distinguishes it from sibling tools focused on CRUD, archiving, or keyword search, making the purpose unambiguous.

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

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

The description explicitly lists situations to use the tool (e.g., find specific information across documents, get direct answers). However, it does not mention when not to use it or provide explicit alternatives, though sibling tools like search_documents or read_document serve different purposes.

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

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

Discloses sequential processing, continues on failure, automatic rate limiting, and the effect on documents (removed from collections but remain searchable). Annotations (destructiveHint: true, idempotentHint: true) are consistent and description adds significant behavioral context beyond them.

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 short paragraphs, bullet points, and clear sections. Every sentence adds value; no fluff. Front-loaded with purpose and behavior.

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 operation (1 param, basic archiving), the description fully covers purpose, behavior, usage, and return type. Output schema exists to detail return values. No 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?

Only one parameter (document_ids). Schema description coverage is 0%, but description repeats 'List of document IDs to archive' which adds little beyond the schema. No details on format, limits, or constraints for the array items.

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 archives multiple documents in a batch, distinguishing from siblings like archive_document (single) and batch_delete_documents (deletion vs archive). Specific verb+resource: 'batch archive 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 use cases (archive multiple outdated docs, clean collections, batch hide) and a recommended batch size. Lacks explicit when-not-to-use or alternative tools, 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?

Discloses sequential processing with continuation on failure and automatic rate limiting. Annotations indicate destructiveHint and idempotentHint; description adds operational details 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?

Well-structured with clear sections: purpose, behavior, parameter details, usage scenarios. Slightly verbose but each sentence adds value. Could be tightened 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?

Covers all critical aspects: purpose, parameters, behavior, usage, and a rendering note. Although no output schema is provided, the description mentions a summary with IDs and success/failure, which is sufficient 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?

With 0% schema coverage, the description fully compensates by detailing all expected fields (title, collection_id, text, parent_document_id, publish) and their required/optional status, providing essential guidance beyond the open-ended 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 creates multiple documents in a single batch operation. It distinguishes from single document creation and other batch operations by specifying bulk creation, but does not explicitly contrast with sibling 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?

Provides explicit use cases: creating multiple documents, bulk import, setting up structures. Includes a notable tip about Mermaid code fences. Does not explicitly exclude single-document use, but implication 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?

Explains sequential processing, continuation on failure, automatic rate limiting, and the behavior of permanent=false (trash, 30-day retention) vs. permanent=true (immediate deletion). Annotations confirm destructiveHint=true and idempotentHint=true, with 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?

Well-structured with clear sections, bold note, bullet points, and parameter descriptions. 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?

Covers all aspects: purpose, usage, behavior, parameters, and return value. Output schema is referenced (summary of operation), and the description is adequate for an agent to correctly invoke the 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?

Despite 0% schema description coverage, the description fully explains both parameters: document_ids as list of IDs, permanent as toggle for full deletion. This adds meaning beyond the schema's minimal metadata.

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 with options for trash or permanent deletion. It distinguishes from siblings like delete_document (single) and archive_document by specifying batch 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?

Provides explicit use cases (bulk removal, workspace cleanup, permanent delete of sensitive data) and a recommended batch size. Implicitly differentiates from single-document operations.

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

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

Discloses sequential processing, error continuation, automatic rate limiting, and child document movement. Annotations (destructiveHint=true, idempotentHint=true) are not contradicted; description adds valuable 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?

Well-structured with clear sections, use cases, and parameter list. Concise yet comprehensive; 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?

Description covers purpose, usage, behavior, parameters, and return type (summary with success/failure). With output schema present, return value is adequately described. No gaps given tool complexity.

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

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

Schema coverage is 0% (no descriptions in schema); description compensates fully by explaining each parameter, noting optionality of collection_id and parent_document_id, and stating requirement to specify at least one of them.

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 moves multiple documents to a different collection or parent, with specific verb 'Moves' and resource 'documents'. Distinguishes from siblings like 'move_document' (single) and batch tools for different 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 use cases (reorganize, move between collections, restructure hierarchies) and suggests batch size (10-50). Does not explicitly exclude single moves, but the sibling 'move_document' implies alternative. Lacks explicit 'when not to use' but still 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 indicate mutating, destructive, and idempotent behavior. The description adds that processing is sequential, continues on individual failures, and handles rate limiting. This gives the agent a clear behavioral model 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 headline, bullet points for usage, a note, batch size recommendation, and parameter listing. 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 tool's complexity (batch operation with partial failures), the description covers failure handling, rate limiting, batch size, parameter semantics, and usage patterns. The presence of an output schema means return values don't need further explanation.

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

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

The input schema has 0% parameter description coverage, but the description details each field in the update dictionary (id, title, text, append) with required/optional flags and meaning. This fully compensates for the schema's lack of 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 'Updates multiple documents with different changes,' which is a specific action on a specific resource. It distinguishes from sibling tools like update_document (single) and batch_archive_documents (different 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?

Explicit usage scenarios are listed ('Use this tool when you need to...') with bullet points covering common cases. It also provides a recommended batch size. Missing explicit alternatives like 'use update_document for single updates,' but still strong 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 indicate readOnlyHint=false and destructiveHint=false, so the description adds that it returns a result with a new collection ID. However, it does not discuss side effects, authentication needs, or constraints like name uniqueness.

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 sections, but could be slightly more concise. Every sentence adds value.

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

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

Given the simplicity of the create tool, the description adequately covers purpose, parameters, and return value. It does not mention error scenarios or prerequisites, but the presence of an output schema reduces the need for 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?

The schema has 0% description coverage, but the description's Args section explains each parameter with meaningful context (e.g., color is a hex code for visual identification).

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 collection for organizing documents, with specific use cases listed. It distinguishes from sibling tools like delete_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 lists when to use the tool (e.g., create a new section, set up a workspace), but does not explicitly state when not to use it or mention 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 indicate mutation (readOnlyHint=false) and non-idempotency (idempotentHint=false). The description adds value by detailing the publish parameter behavior (publish vs draft) and a rendering note about Mermaid code fences. It also mentions the return format (result message with new document ID).

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. It starts with a clear statement, uses bullet points for use cases and parameters, and includes a specific note on Mermaid. The use case list is somewhat redundant with the purpose, but overall structure is good.

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 0% schema coverage and presence of annotations and output schema, the description covers tool purpose, parameters, and return value adequately. It lacks details on constraints (e.g., title uniqueness) or error conditions, but is sufficient for basic usage.

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 all five parameters: title, collection_id, text (optional markdown), parent_document_id (optional for nesting), and publish (True=publish, False=draft). This compensates completely 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 explicitly states 'Creates a new document in a specified collection' and lists specific use cases (add new content, create documentation, add child document), clearly distinguishing it from sibling tools like update_document or archive_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 provides a 'Use this tool when you need to' list that covers typical creation scenarios (add to knowledge base, create docs, nest under parent). It does not explicitly state when not to use it, but the context and sibling names imply alternatives for updating or deleting.

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

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

Annotations indicate destructiveHint=true and idempotentHint=true. The description adds that the action is permanent, cannot be undone, and deletes all documents, providing necessary behavioral context beyond structured 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?

The description is concise with bullet points for use cases and a clear warning. Every sentence adds value, and it is front-loaded with the primary 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?

For a simple 1-parameter tool with output schema, the description covers purpose, usage, warning, parameter, and return. No significant 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 sole parameter collection_id is explained in the description as 'The collection ID to delete,' adding meaning despite 0% schema coverage. The parameter's purpose is clear from context.

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

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

The description clearly states 'Permanently removes a collection and all its documents,' using a specific verb-resource pair. It distinguishes from sibling tools like delete_document and create_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?

The description provides clear use cases (remove section, delete obsolete, clean up) and a warning about irreversibility. It does not explicitly exclude alternatives or compare with batch_delete_documents, but context 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?

Adds significant context beyond annotations: describes default behavior (trash with 30-day retention), permanent deletion option, and recovery via restore_document. No contradictions with annotations (destructiveHint=true, readOnlyHint=false, idempotentHint=true).

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 for purpose, usage, args, and returns. Front-loaded with main action. Slightly verbose but clear; could be tightened without losing information.

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

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

Covers purpose, parameters, return value, and behavioral notes. Mentions interaction with restore_document. Could benefit from differentiation from sibling tools like archive_document or batch_delete_documents, but is adequate for a simple 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?

Despite 0% schema description coverage, the description includes an 'Args' section that explains both parameters (document_id and permanent) in detail, adding meaning beyond the schema's type and title. Includes default value for permanent.

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 'Moves a document to trash or permanently deletes it', specifying the verb and resource. It distinguishes from sibling tools like archive_document and batch_delete_documents by detailing the deletion behavior (trash vs permanent).

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 such as removing unwanted documents, deleting obsolete content, and cleaning up workspace. Mentions restore_document for recovery. However, lacks explicit exclusions or alternatives among siblings (e.g., when to use archive_document instead).

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 (readOnlyHint, destructiveHint, idempotentHint), the description details that the tool starts an asynchronous operation, may take time, returns operation info, and file access via UI. This adds significant 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 well-structured with a clear first sentence, a block on async behavior, use cases, and args. 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's complexity (async export), the description covers key aspects: purpose, format, async behavior, and access. It's complete enough for an agent to understand and use the tool, though more detail on status checking could be added.

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 'format' has no schema description (0% coverage), but the description lists allowed values ('outline-markdown', 'json', 'html') and explains its purpose, fully compensating for the schema gap.

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

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

The description explicitly states 'Exports the entire workspace content to a downloadable file,' clearly identifying the verb (exports) and resource (entire workspace). It distinguishes from sibling tools like export_collection and export_document, which export single collections or 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 lists concrete use cases (create backup, migrate, archive, comprehensive export), giving clear context. It implicitly distinguishes from single-export tools but does not explicitly 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?

Adds value beyond annotations by describing the async operation and file access method; annotations already declare readOnlyHint, destructiveHint, idempotentHint, and description aligns with those.

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, concise, 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?

Covers async behavior, file access, and purpose; slightly vague about how to use the returned operation info, but adequate given presence of 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%, but description only briefly mentions parameters without adding meaning (e.g., does not list format options). Fails to compensate for 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?

Clearly states 'Exports all documents in a collection to a downloadable file,' distinguishing from siblings like export_document and export_all_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?

Lists specific use cases (backup, share, convert, archive) and mentions asynchronous nature, but does not explicitly exclude use of alternatives or provide 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 provide readOnlyHint and idempotentHint. Description adds that the output is 'markdown format without additional formatting', which is useful beyond annotations. 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?

Concise with clear sections (purpose, usage bullets, Args, Returns). Front-loads the main verb and resource. No wasted words.

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

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

Given low complexity (1 param, no nested objects, output schema present), the description fully covers what the tool does and returns. The Returns section explains output format.

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

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

Schema coverage is 0%, but the description's Args section clearly explains 'The document ID to export', adding meaning beyond the schema's 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 uses specific verb 'Exports' and resource 'document as plain markdown text', clearly distinguishing it from siblings like read_document (which likely returns formatted content) and other export tools (export_collection, export_all_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?

Explicitly lists when to use the tool (e.g., 'Get clean markdown content without formatting'). While it doesn't mention when not to use it or alternatives, the use cases are clear and help the agent 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 that it returns a formatted string showing hierarchical structure, providing context beyond structured data.

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

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

Well-structured with bullet points and sections, concise yet informative. 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's simplicity (one parameter, output schema exists), the description adequately covers the retrieval purpose and return format. No major gaps.

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

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

Schema coverage is 0%, but description adds 'The collection ID to examine' for the single parameter collection_id, which provides meaning beyond the schema title.

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

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

The description states it retrieves the hierarchical document structure of a collection, with specific use cases. It clearly distinguishes from sibling tools like list_collections 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?

Description explicitly lists four scenarios for using the tool. However, it does not mention when not to use it or provide alternative tools for similar tasks.

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=true and idempotentHint=true, confirming no side effects. The description adds value by stating the return format ('Formatted string with the comment content and metadata') and explaining the effect of the 'include_anchor_text' parameter. It provides behavioral context 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 succinct at ~10 lines, with a clear structure: opening verb statement, bulleted use cases, 'Args' section, and 'Returns' note. Every sentence serves a purpose, and key information is front-loaded. There is no redundancy or waste.

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

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

Given the tool's simplicity (single resource retrieval), the description covers all necessary aspects: purpose, parameter explanations, return format, and common use cases. It is complete for the complexity level, and the presence of an output schema reduces the need for extensive return 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 input schema has no descriptions (coverage 0%), so the description fully carries the burden of explaining parameters. It provides clear explanations: 'comment_id: The comment ID to retrieve' and 'include_anchor_text: Whether to include the document text that the comment refers to'. While straightforward, this adds essential meaning and earns a 4.

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 'Retrieves a specific comment by its ID,' which is a specific verb+resource combination. It lists distinct use cases (view details, reference, quote, check content, find a comment) that clearly differentiate it from sibling tools like 'list_document_comments' (lists all) and 'add_comment' (creates). The purpose is unambiguous and scoped.

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

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

The description explicitly states when to use this tool (e.g., to view details, reference a comment, check content, find a comment mentioned elsewhere). It provides clear context but does not explicitly exclude alternatives or contrast with siblings. The usage cases are well-defined, earning a 4.

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 that it returns a formatted string and details the argument. It is consistent with annotations and provides 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?

The description is well-structured with a purpose statement, use-case list, and sections for args and returns. It is concise, though the bullet list could be slightly trimmed without losing 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?

For a single-parameter tool with output schema indicated, the description provides a reasonable overview. It specifies the return type (formatted string) but lacks details on the format or any edge cases.

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 for the parameter 'document_id' merely restates 'The document ID to find backlinks for,' adding little beyond the schema's title. With 0% schema description coverage, the description fails to compensate with format, constraints, or examples.

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.' It uses a specific verb and resource, and distinguishes it from sibling tools by focusing on backlinks as a unique relationship.

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 a bullet list of use cases (discover references, identify dependencies, find related documents), but does not explicitly contrast with alternatives like search_documents or specify when not to use 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 indicate readOnlyHint and idempotentHint. The description adds valuable behavioral details: case-insensitive exact match first, then best partial match fallback, and accuracy improving with more title input. 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 a clear opening sentence, an important note, and a bulleted list of use cases. It is not overly long, but the IMPORTANT section 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 simplicity (2 parameters, output schema present), the description covers the main behavior, return value, and use cases effectively. The mention of 'best match information' in returns is adequate without duplicating the 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 description coverage is 0%, so the description must compensate. It briefly explains both parameters: 'query: Title to search for (can be exact or partial)' and 'collection_id: Optional collection to limit search.' This adds basic meaning but lacks detail on 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's function: 'Locates a document ID by searching for its title.' It also explains the matching behavior (exact then partial), which distinguishes it from sibling search tools like 'search_documents' or 'read_document'.

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

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

The description explicitly lists four use cases for when to use the tool, such as finding an ID when only the title is known or verifying existence. It lacks explicit 'when not to use' guidance but provides clear context for appropriate usage.

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

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

Annotations already indicate readOnlyHint, destructiveHint, idempotentHint. The description adds that it returns a formatted string, which is minimal additional context. With annotations present, a baseline score of 3 is appropriate as the description does not deeply elaborate on behavior.

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

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

The description is brief and well-structured: a clear opening sentence, bullet list of use cases, and a line about the return value. No extraneous content; each part earns its place.

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

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

Given the tool's simplicity (no parameters, output schema present), the description adequately covers what the tool does and returns. It could specify if the list is limited to the current workspace or user, but the scope is implied. With an output schema, the description is sufficiently 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 tool has zero parameters, so the description need not add parameter details. According to guidelines, baseline for 0 params is 4. The description's mention of return format adds nominal 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 'Displays all documents that have been archived.' and enumerates specific use cases, making the tool's purpose unambiguous. It distinguishes itself from sibling tools like list_trash and list_collections by focusing on 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?

The description lists explicit use cases (find, review, identify for unarchiving, check status), providing clear context for when to use the tool. However, it does not contrast with alternatives or provide when-not-to-use guidance, preventing a top score.

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 the description's safety profile is clear. The description adds value by specifying the return format (formatted string with names, IDs, descriptions), which is useful beyond the annotations. 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 is concise and well-structured: a clear one-line purpose, a bullet list of use cases, and a return format note. Every sentence serves a purpose 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 (no parameters, read-only), the description completely covers what the tool does, when to use it, and what it returns. The output format is described, and with the output schema present, no further details are needed.

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 the input schema provides no additional details. The description correctly omits parameter explanations, aligning with the baseline score of 4 for zero-parameter tools. The description does not need to add meaning beyond what the schema provides.

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 available collections, with a specific verb and resource. It distinguishes itself from sibling tools that modify collections (e.g., create_collection, delete_collection) by focusing on listing, making the purpose unambiguous.

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

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

The description provides explicit use cases (e.g., see collections, get IDs, explore organization, find by name) which guide when to use it. It does not directly mention when not to use it or compare with alternatives, but given the context of read-only operation, this is adequate.

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

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

Annotations indicate readOnlyHint and idempotentHint. The description adds value by explaining pagination behavior (default 25, need multiple calls for more, response indicates availability). No contradictions, and it supplements the annotations 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 clear sections (purpose, important note, use cases, args, returns). It is not overly long, though some repetition exists (e.g., 'Retrieves comments' and bullet points).

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 (1 required), no enums, and presence of output schema, the description covers parameter details, output format, and pagination. It does not address error handling or rate limits, but overall sufficient 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?

Schema coverage is 0%, so the description carries full burden. It explicitly lists and describes all four parameters (document_id, include_anchor_text, limit, offset) with defaults, adding meaning beyond the schema. Lacks constraints or examples.

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 'Retrieves' and resource 'comments on a specific document', and highlights pagination support. This distinguishes it from siblings like 'get_comment' (single comment) and 'add_comment' (write).

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 (review feedback, see all comments, etc.) and provides an important pagination note. However, it lacks explicit guidance on when not to use this tool (e.g., for a single comment, use get_comment).

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, destructiveHint, idempotentHint. Description adds that it returns a formatted string, complementing 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?

Concise, well-structured with bullet points for use cases and a clear return statement. No unnecessary 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?

Complete for a no-param tool with annotations and output schema. Covers purpose, usage, and return format.

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; schema coverage 100%. Baseline 4 is appropriate as description adds no parameter details needed.

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 currently in the trash' with specific verb and resource, and 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?

Explicitly lists use cases (find deleted documents, review pending deletion, identify to restore, verify deletions). No exclusion of alternatives, but context provided.

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

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

Annotations indicate destructiveHint=true, and description adds that moving a document with children moves them all, which is critical behavior. 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 and bullet points. Front-loaded with purpose. The Args section slightly redundant with schema but acceptable.

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 key behavior (child documents) and basic return value. Given annotations and output schema (existence noted), the description is adequate.

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's role and the constraint that at least one of collection_id or parent_document_id must be provided.

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 relocates a document to a different collection or parent document. It uses specific verbs and distinguishes from siblings like batch_move_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 use cases (reorganize hierarchy, move to collection, change parent) and includes an IMPORTANT note about child documents. Lacks explicit '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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to reiterate safety. It adds context by specifying the return format ('Formatted string containing the document title and content'), but does not detail potential error behavior or other behavioral traits.

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 main statement, bulleted use cases, and separate Args/Returns sections. It is concise (about 80 words) and every sentence adds value, with no redundancy or filler.

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

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

Given the simple input (one parameter), complete annotations, and presence of an output schema, the description covers purpose, usage, parameter explanation, and return format. Minor omissions like error handling do not significantly detract from completeness for this 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 input schema has 0% description coverage, but the description's 'Args' section adds meaningful context: 'document_id: The document ID to retrieve'. This explains the parameter's purpose beyond the schema's type/required, compensating 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 the verb 'retrieves and displays' and the resource 'full content of a document'. It distinguishes itself from sibling tools like create_document or delete_document by focusing on read-only access to full content.

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

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

The description explicitly lists four use cases ('Access the complete content...', 'Review document information...', etc.), providing clear guidance on when to use the tool. However, it does not mention when not to use it or contrast with similar read tools like search_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 indicate idempotentHint=true, and the description adds context about restoring from trash within the last 30 days and accessing previously trashed content. No contradictions, and adds non-obvious details.

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

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

The description is well-structured with a clear overview and bullet points for use cases. Each sentence adds value, no fluff or redundancy.

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

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

For a single-parameter tool with straightforward functionality, the description covers purpose, usage guidance, return value (via output schema), and behavioral constraints. It is complete for the complexity level.

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 one parameter with no description. The description simply restates it as 'The document ID to restore'. With 0% schema coverage, this adds minimal 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 the tool's action ('Recovers a document from the trash back to active status') and specifies the resource (document). It is distinct from siblings like 'delete_document', 'archive_document', and 'unarchive_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 explicitly lists use cases (retrieve accidentally deleted, restore from trash, etc.), providing clear context. It does not explicitly state when not to use it, but the purpose is well-defined.

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 full-text search behavior, relevance ranking, snippet inclusion, and pagination. Annotations already indicate read-only and idempotent, so 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?

Well-organized with sections (IMPORTANT, PAGINATION, Use when, Args, Returns). No wasted sentences; every line 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?

Covers pagination, snippets, ranking, and return format. Output schema exists but description enhances understanding. Complete for a search 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 0%, but description provides full parameter explanations (query terms, collection_id optional, limit default/max, offset default).

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?

Searches for documents using keywords/phrases across knowledge base; verb 'searches' and resource 'documents' are specific. Distinguished from siblings (e.g., read_document, 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?

Explicit when-to-use scenarios listed (find terms, locate info, search within collection, browse results). Sibling tools are distinct, but no when-not-to is needed given clarity.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false. The description adds that it restores to active status and returns a confirmation, which is consistent and mildly informative.

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 brief, well-structured, and front-loaded with the main action. Every sentence serves a purpose 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 and the presence of output schema (not shown), the description covers the essential usage, return value, and parameters. No additional information is necessary for correct invocation.

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

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

The description explains document_id as 'The document ID to unarchive,' which closely mirrors the schema's title. With only one simple parameter, the added value is minimal; schema coverage is 0% but the parameter is straightforward.

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: 'Restores a previously archived document to active status.' It lists specific use cases and implicitly distinguishes from siblings like archive_document and restore_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 'Use this tool when you need to:' bullets provide clear context for when to use the tool. However, it does not explicitly state when not to use it or directly mention alternatives, though siblings are listed separately.

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 the description's 'modifies' adds little beyond that. It lists what properties can be changed but does not disclose side effects, permission needs, or behavior when optional fields are omitted (e.g., whether they remain unchanged). Slightly above minimal given annotation coverage.

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

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

Efficiently structured: one opening sentence, bullet list of use cases, then Args with inline descriptions, and a Returns line. No redundant information. Every sentence adds value. Front-loaded with 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 an output schema exists, the return value description is sufficient. All parameters are explained, use cases are covered, and the tool's purpose is clear. However, it could mention prerequisites (e.g., collection must exist) or that other properties not listed remain unchanged. Still, comprehensive for a moderate-complexity tool.

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

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

Schema description coverage is 0%, so the description carries full burden. Args section adds meaningful context: 'name' is 'Optional new name', 'color' is 'Optional new hex color code (e.g. #FF0000)'. This substantially aids an agent in understanding parameter usage beyond the schema titles.

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 'Modifies an existing collection's properties' with a specific verb and resource. Lists concrete use cases (rename, update description, change color coding, refresh metadata) that directly address the tool's function, distinguishing it from siblings like create_collection and 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?

Provides explicit list of when to use (rename, update description, etc.) via a bulleted list. While it does not explicitly state when not to use or name alternatives, the use cases are clear and sufficient for an agent to decide. Lacks exclusionary guidance but still strong.

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: it warns that content is replaced (not just appended) unless the append parameter is true, and includes a specific formatting note for Mermaid diagrams. Annotations already indicate destructiveHint=true, and the description reinforces this 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 purpose sentence, important note, bullet points, and a formatted Args section. While slightly lengthy, each part adds value and is front-loaded with key behavior. Minor redundancy (e.g., 'append' in both usage and parameter description) but overall effective.

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

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

The description covers purpose, parameter semantics, and key behavioral traits. An output schema exists, so the brief mention of the return value is acceptable. However, it could be improved by noting typical error scenarios (e.g., invalid document_id) or confirming that the output object contains updated document fields.

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

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

With 0% schema description coverage, the description carries the full burden. It explains each parameter (document_id, title, text, append) with clear behavior (e.g., 'if None, keeps existing'). This adds meaning beyond the schema's type and default values.

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

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

The description clearly states the tool modifies an existing document's title or content, and lists specific use cases (edit, change title, append). This distinguishes it from siblings like create_document (creates new) or read_document (read-only).

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 in bullet points and includes an important note about content replacement. However, it does not explicitly state when not to use this tool (e.g., for creating new documents) or compare to alternative sibling tools.

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