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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description adds that archiving is reversible, which is critical behavioral context. It also notes write access requirement. However, it does not explain what happens to an already archived document or the exact 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 a single concise sentence with no wasted words. It front-loads the core action and additional details (reversible, restore, access requirement) efficiently.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description covers the basic purpose and reversibility but omits any mention of return values or what the tool does if the document is already archived/trashed. It is adequate 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?

With 0% schema description coverage, the description does not explain the 'id' parameter (document ID) or explicitly detail the 'action' enum values beyond natural language. The action is partially implied, but the required id is not mentioned.

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

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

The description clearly states the tool's purpose: archiving a document (reversible) or restoring an archived/trashed one. It explicitly distinguishes from sibling tools like outline_delete_document by noting reversibility.

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 mentions 'Requires write access' as a prerequisite but does not provide guidance on when to use this tool versus alternatives like outline_delete_document or outline_move_document. The purpose implies usage, but no explicit when-not or alternative comparisons.

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 and destructiveHint=false. Description adds that write access is required and explains parentCommentId behavior for threading. However, it does not disclose other behavioral details such as error handling or limits 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?

A single concise sentence of 15 words front-loads the action and adds key detail about parentCommentId. No redundant 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?

Description covers purpose, permission, and one parameter, but lacks guidance on return values (no output schema) and error conditions. For a simple creation tool, it is minimally adequate but could be more helpful.

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 only explains parentCommentId as 'replies to a thread', providing no additional meaning for 'text' or 'documentId'. This leaves major gaps for the two required parameters.

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

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

Description states 'Add a comment to a document' with specific verb and resource. It also notes that parentCommentId is for replying to a thread, distinguishing from sibling tools like outline_list_comments or outline_create_document.

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

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

Description includes 'Requires write access' as a prerequisite, but does not explicitly state when to use this tool versus alternatives like outline_list_comments or outline_update_document. Usage context is implied but not fully clarified.

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 (write operation). The description adds behavioral context: publish makes the document visible, parentDocumentId nests it. 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?

One efficient sentence that immediately states purpose and two key parameters, 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 the main purpose and two optional parameters, but omits return value (no output schema) and does not explain title or collectionId parameters beyond minimal schema constraints.

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

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

Schema description coverage is low (20%: only 'text' has a description). The description explains publish and parentDocumentId, partially compensating, but leaves title and collectionId without additional meaning.

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

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

The description clearly states the tool creates a document in a collection with Markdown body, and distinguishes it from sibling tools like outline_update_document and outline_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 mentions 'Requires write access' and explains key parameters (publish, parentDocumentId), but does not explicitly state when to use this tool versus alternatives like outline_update_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?

Adds context beyond annotations: clarifies recoverable nature (aligns with destructiveHint=false) and explicit write access requirement. 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?

Two concise sentences, front-loaded with the core action. No extraneous words.

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

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

Covers purpose, recoverability, and authorization. Missing minor details like id format or error cases, but sufficient 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?

With 0% schema coverage, description adds no information about the single parameter 'id'. While the meaning is obvious, the description 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 the action: moving a document to Trash (recoverable). Distinguishes from permanent deletion but not from archive sibling.

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

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

Provides implicit guidance: use when you want recoverable deletion. Mentions write access requirement and that permanent deletion is not available, but no explicit comparison 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, covering the safety profile. The description adds behavioral context by noting that 'includeStructure=true adds its document tree', which is beyond what annotations provide. 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 a single sentence that is front-loaded with the action. Every word is necessary and no extraneous information is present. It is exceptionally 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 low complexity (2 params, simple) and the presence of annotations, the description covers the core purpose and a key behavioral detail. It does not explain return values, but no output schema exists. The description is nearly complete for its context, though a brief note about the response format would improve it.

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

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

With 0% schema description coverage, the description must compensate. It adds meaning to the 'includeStructure' parameter by explaining its effect. However, it does not describe the 'id' parameter or its format, leaving a gap. The description provides partial but insufficient semantics for both parameters.

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

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

The description clearly states 'Fetch one collection', which specifies the verb and resource. It also distinguishes the tool from sibling 'outline_list_collections' by indicating it fetches a single collection. The mention of 'includeStructure' adds specificity about an optional feature.

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

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

The description implicitly guides usage: use this tool to fetch a single collection by ID, vs 'outline_list_collections' for listing all. However, it does not explicitly state when to use this tool over alternatives or any prerequisites, which would strengthen the 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 declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds behavioral detail about the asMarkdown parameter returning full Markdown body, which is beyond annotations. It does not contradict annotations.

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

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

Two concise sentences with no extraneous information. The key behavior and parameter are front-loaded, making it efficient.

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

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

The description explains the asMarkdown behavior and the identifier methods, but does not describe the default return format (without asMarkdown) or error cases. Given no output schema, this is a minor gap; annotations provide safety 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?

Schema covers two parameters with id having a description but asMarkdown lacking one. The description compensates by explaining asMarkdown=true returns full Markdown body, adding value to the semantics.

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 fetches a document by id or slug, using a specific verb 'Fetch' and resource 'document'. This distinguishes it from sibling tools like outline_list_documents or outline_search.

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

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

The description implies usage by identifying the primary identifier (id or slug) and a key flag (asMarkdown), but does not explicitly state when to choose this over alternatives like outline_get_collection or outline_search. However, the purpose is straightforward and self-explanatory.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds no behavioral detail beyond annotations, such as pagination behavior or return structure.

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

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

The description is a single sentence, which is overly brief. It lacks necessary detail about parameters and usage, making it under-specified rather than 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 two undocumented parameters and no output schema, the description should explain pagination and output expectations. It does not, leaving the agent underequipped to use the tool correctly.

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

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

Schema description coverage is 0%, and the description does not explain the 'limit' and 'offset' parameters. The agent lacks guidance on how pagination works, potentially misusing the tool.

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

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

The description clearly states the action (list) and resource (collections in the workspace). It distinguishes from siblings like outline_get_collection (single) and outline_manage_collection (mutate).

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

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

No guidance on when to use this tool versus alternatives. It doesn't mention that it lists workspace-wide collections, nor does it exclude filtering or sorting. Siblings like outline_search exist but are not referenced.

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 the tool is read-only, idempotent, and not destructive. The description adds no further behavioral context, such as pagination behavior or ordering, but 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 (one sentence) and front-loaded, but it is too brief, omitting critical details about parameters and behavior, reducing its usefulness.

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 lack of output schema and low schema coverage, the description should provide more context about return format, pagination, and required parameters. It fails to adequately guide the 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 schema description coverage at 0%, the description provides no information about the parameters (documentId, limit, offset). The agent must rely solely on parameter names, which is insufficient for proper invocation.

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 (list) and resource (comments on a document). It distinguishes from sibling tools like outline_create_comment and outline_list_documents, which focus on different actions or resources.

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

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

No guidance is provided on when to use this tool versus alternatives, such as outline_create_comment or outline_get_document. The description lacks context about filtering or other usage 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 readOnlyHint=true and destructiveHint=false. The description adds the filter enumeration and optional collection scope, which are useful but do not significantly expand on behavioral traits 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?

Single sentence of 20 words, no fluff. Efficiently communicates the core functionality.

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 the main purpose and filter options, but lacks details on pagination (limit/offset) and return format. For a simple list tool, this is adequate 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 coverage is 0%. The description explains 'filter' options and 'collectionId', but does not describe 'limit' or 'offset' parameters, leaving pagination behavior undocumented.

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 documents' with specific filter options (recent, drafts, archived, deleted) and optional collection scoping. It distinguishes from siblings like 'outline_get_document' (single document) and write 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?

No explicit when-to-use or alternatives are provided. The description implies usage for listing documents in various states, but does not contrast with other listing or search tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds minimal context about optionally retrieving a single revision via revisionId, but does not discuss pagination behavior, return format, or API limitations.

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 very short (one sentence), but the sentence structure is awkward and could be misinterpreted. It is concise but at the expense of clarity.

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

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

With no output schema, the tool needs to describe its return value. It does not. Pagination parameters (limit, offset) imply a list response, but this is not confirmed. The optional revisionId behavior is not fully explained.

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. The description mentions revisionId only in passing, without explaining its effect. Parameters documentId, limit, offset are not described at all.

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 'A document’s version history, or one revision with revisionId' vaguely conveys it lists revisions or retrieves a single one, but the phrasing is ambiguous. The title 'List Revisions (Outline)' is clearer but not expanded upon.

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

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

No guidance is provided on when to use this tool versus sibling tools like outline_get_document or outline_list_documents. There are no when-to-use or when-not-to-use indications.

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 this is a write operation (readOnlyHint=false). The description adds important context that deletion is permanently cascading and not available, which is a critical behavioral trait not covered by annotations.

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

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

Two sentences, front-loaded with purpose, no fluff. Every sentence provides essential information: actions, scope, deletion note, access requirement.

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 (two operations, 6 params, no output schema), the description covers the key points: actions, updatable fields, permission requirement, and deletion warning. Missing details like id usage for update and return value, but overall 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 has 6 parameters with 0% description coverage. The description partially compensates by mentioning name, description, and permission as fields that can be set, but does not explain id, color, or action parameter semantics, leaving gaps.

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 creates or updates collections, specifying the resource (collection) and actions. Distinguishes from sibling tools like outline_list_collections or outline_get_collection which are 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?

Specifies when to use (create/update) and explicitly states that deletion is not available, preventing misuse. Mentions required write access, but does not explicitly contrast with other tools for reading or managing collections beyond this one.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false. Description adds 'Requires write access' which aligns with mutation nature. No contradictions, but beyond that, no additional behavioral traits disclosed (e.g., side effects on permissions or URLs). Minimal added value over 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?

Extremely concise: two sentences that front-load the core purpose and a necessary prerequisite. Every word is relevant and no superfluous 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?

Given the tool's simplicity (3 params, no output schema), the description should cover basic behavioral context such as what happens to the document's position, any side effects on URLs or permissions. The description is too brief and leaves important aspects unspecified.

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 must compensate. It implicitly references collectionId and parentDocumentId but does not explain their semantics, format, or optionality. The required 'id' parameter is not described at all. Fails 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?

Description clearly states the action (move) and resource (document), and specifies it can be to another collection and/or under another parent document. This distinguishes it from siblings like outline_archive_document, outline_delete_document, 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?

Description mentions prerequisite 'Requires write access' but does not provide explicit guidance on when to use versus alternatives or when not to use. Context is implied but lacks exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, which cover safety. The description adds behavioral specifics: results are ranked and include context snippets. No contradictions are present.

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

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

The description is a single sentence that efficiently conveys the core functionality and lists filters. It is front-loaded with the primary action and result type, with 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 the main behavior and optional filters. Given the annotations (read-only, idempotent) and schema (which includes pagination parameters), the description is adequate but could mention pagination (limit/offset) to be fully self-contained. No output schema is present, but the description implies the return of search results with snippets.

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 lists the key optional filters (collectionId, statusFilter, dateFilter, userId) and explicitly provides allowed values for enums (e.g., draft/published/archived, day/week/month/year). It does not mention limit, offset, or query, but query is implied by 'full-text search'. This adds meaningful context beyond the bare schema.

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

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

The description clearly states 'Ranked full-text search with context snippets', specifying the verb (search), resource (documents), and the nature of results (ranked, with snippets). This distinguishes it from sibling tools like outline_list_documents (listing without search) and outline_get_document (single document retrieval).

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

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

The description implicitly indicates use for full-text search with optional filters, and the sibling tools provide context for alternatives. However, it lacks explicit 'when-to-use' or 'when-not-to-use' guidance, such as specifying that this tool is preferable to outline_list_documents when search is needed.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds that the tool searches capabilities (a meta-search), but does not elaborate on behavioral details such as response format or pagination. This is adequate but not rich, so a 3 is appropriate.

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

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

The description is a single concise sentence that front-loads the purpose. However, it could be more efficient by including parameter hints without adding much length. It earns points for being short but loses some for missing detail that would improve utility.

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 lacks any explanation of what the tool returns (no output schema) and does not describe the search syntax or how to effectively use the query parameter. For a tool intended as a first-resort for tool selection, this incompleteness hampers an agent's ability 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?

Schema description coverage is 0%—neither parameter (limit, query) is explained in the schema. The description does not mention or explain the parameters at all (e.g., what the query expects, how limit affects results). For a tool with two parameters and no schema descriptions, the description should compensate but fails to do so, resulting in a low score.

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 'Search the Outline/Playbook MCP capabilities' and adds 'Use first when deciding which tool to call,' distinguishing it from sibling tools like outline_search (which presumably searches documents). The verb 'search' and resource 'capabilities' are specific and the purpose is unambiguous.

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

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

The description explicitly says 'Use first when deciding which tool to call,' providing clear guidance on when to use this tool. It implies a sequence (first step in tool selection) but does not provide explicit when-not-to-use scenarios or mention alternatives like outline_search, so there is some room for improvement.

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, describes append behavior (add vs replace) and write access requirement. 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?

Two concise sentences front-load the purpose. No wasted words, but could be slightly more structured.

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 no output schema and 5 parameters, the description explains key behavior but misses 'publish' and response details. 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?

With 0% schema coverage, description explains append and distinguishes replace, but lacks details on 'publish' parameter and doesn't clarify title update behavior (replace or partial update).

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 updates a document's title or body, distinguishing from creation, archiving, and deletion siblings. The append behavior is explicitly defined.

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?

Explains when to use append vs replace and mentions write access requirement. Could explicitly compare with other tools but is already 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, openWorldHint, idempotentHint, and destructiveHint=false, so the agent knows this is a safe, idempotent read operation. The description adds the specific output context: it shows user and workspace. 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?

Single sentence, front-loaded with purpose, no extraneous words. Highly efficient for a zero-parameter tool.

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

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

For a simple identity tool with no parameters and no output schema, the description adequately conveys what it does. However, it omits any mention of the return format (e.g., JSON with user and workspace fields). Given the lack of output schema, a brief note on output structure would improve completeness. Still, the core purpose is clear.

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 are zero parameters, and schema description coverage is 100% (nothing to describe). Per guidelines, baseline is 4. No additional parameter meaning 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?

Description clearly states the tool shows the user and workspace associated with the Playbook token. It uses specific verb 'Show' plus the resource (user/workspace identity). This distinguishes it from sibling tools like outline_get_document or outline_search, which have different purposes.

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 implies usage context (when you need to know the current authenticated user/workspace) but does not provide explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned, though siblings suggest identity verification is unique. Lacks explicit exclusions.

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