agentdocs-mcp

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

The description discloses an important behavioral nuance: the mentions array is informational only and does not notify users. This adds value beyond the annotations (readOnlyHint=false), which already indicate a write operation. It does not mention auth or rate limits, but the mention side effect is a valuable transparency addition.

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 deliver the core purpose and a behavioral caveat without filler. The key action and threading instruction are front-loaded, and the mention caveat earns its place.

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

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

The description covers the main behavior, the threading variant, and the mention behavior, which is sufficient for a simple write tool with a well-annotated schema. It does not explicitly state the full return value (e.g., comment ID), but the mention array is addressed and the output schema is absent, so the description carries an acceptable level of 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?

The input schema provides full descriptions for all three parameters (100% coverage), so the baseline is 3. The description adds little new parameter information—it reiterates the parent_comment_id purpose but does not elaborate on the 'page' format or 'content' semantics beyond the schema.

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

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

The description clearly states the action ('Post a comment on a page') and distinguishes from sibling comment tools by focusing on creation and reply threading. The parent_comment_id instruction clarifies the difference between top-level and threaded comments.

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

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

The description gives clear guidance on using parent_comment_id to reply within a thread, which is the key usage distinction. It does not explicitly name alternatives (e.g., update_comment, delete_comment), but the creation context is evident from the name and description.

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 discloses the underlying 'read-modify-write' mechanism and that it 'creates a new version', which is not covered by the annotations (which only indicate non-read-only, non-idempotent, non-destructive). This adds valuable context about side effects and versioning, going beyond the structured metadata.

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

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

The description is two sentences, front-loaded with the action, and contains zero filler. It efficiently conveys what, how, and typical use cases in minimal 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?

For a simple append tool with annotations and full schema coverage, the description adequately covers purpose, behavior, and use cases. It does not mention edge cases (e.g., missing page) or return values, but given the availability of annotations and the simplicity of the operation, it is reasonably complete. A 5 would require explicit handling of failure scenarios or output details.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds no additional meaning beyond what is in the schema: 'page' and 'content' are self-explanatory, and 'separator' is described in the schema. The description's mention of 'Markdown' aligns with the content parameter but does not extend it.

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 ('Append') and resource ('existing page'), clearly distinguishing it from create_page and update_page. It also specifies the input format ('Markdown') and the position ('end'), leaving no ambiguity about the tool's function.

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 ('Ideal for logs, reports, and running notes') and implies when to choose this over update_page by emphasizing append semantics. However, it does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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

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

Annotations are all false and provide no behavioral detail. The description adds crucial behavior: atomicity (all succeed or all fail), the 500-page limit, explicit structure requirement, and token-scoped space behavior. This goes well 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?

Three sentences, each earning its place: capability, alternative tool, and space token guidance. No fluff or repetition.

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

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

For a bulk creation tool with nested objects and no output schema, the description covers the key aspects: limit, atomicity, structure, alternative workflow, and token auth behavior. This is sufficient for an agent to correctly select and 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by clarifying the structure ('titles, slugs, parent_page_id') and the space token behavior ('With a space-scoped token, omit space'). That extra context justifies 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?

Description opens with 'Create up to 500 pages in one atomic call' – a specific verb, resource, and capability. It also distinguishes itself from import_markdown, so it's clear what this tool does vs siblings.

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

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

Explicitly states when to use this tool vs alternative: 'To import a folder of Markdown files and derive the hierarchy from file paths, use import_markdown instead.' Also provides context about space-scoped tokens and omitting 'space'.

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 useful behavioral context beyond the annotations: slug is derived from title unless provided, and space-scoped tokens can omit the space parameter. This helps the agent understand default behavior and token-based scoping, though it does not discuss edge cases like duplicate slugs or permission errors.

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

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

The description is two sentences long, front-loaded with the main action, and contains no redundant filler. Every clause adds useful information.

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

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

For a straightforward create operation with no output schema, the description plus schema covers the required params, slug behavior, and token-specific space handling. It could have mentioned what happens on success (e.g., returns page ID), but the current level is adequate given the tool's simplicity.

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

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

Schema description coverage is 100%, but the tool description adds meaningful semantic detail beyond the schema: it clarifies how slug is generated from title, and when to omit 'space' based on token scope. This goes beyond the bare schema property descriptions.

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

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

The description clearly states the tool's function: creating a Markdown page in a space. The verb 'create' and resource 'page' are specific, and it naturally stands apart from sibling tools like update_page, delete_page, or bulk_create_pages.

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

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

It gives concrete guidance on the optional 'space' parameter for space-scoped tokens, which is a useful conditional use case. It does not explicitly mention alternatives or exclusions, but the guidance is clear enough for an agent to choose this tool over update or append 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 set destructiveHint=true and readOnlyHint=false, but the description goes further by adding 'Permanently delete' to emphasize irreversibility, 'Only the comment's author (or an admin) may delete it' to cover authorization, and 'There is no undo via the API' to highlight a non-obvious consequence. This provides substantial behavioral context beyond the 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 three concise sentences, each earning its place: the core action, the permission constraint, and the irreversibility warning. It is front-loaded with 'Permanently delete a comment' and contains no filler or repetition of schema details.

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

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

For a simple one-parameter delete operation with no output schema and full parameter documentation, the description is complete. It covers what the tool does, who may use it, and a critical side effect (no undo). There are no missing pieces that would prevent an agent from selecting or invoking 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?

The input schema covers the only parameter, 'comment', with a clear description: 'Comment UUID (from get_page include_comments or list_comments).' Since schema coverage is 100%, the description need not add parameter details, and it does not—it only references 'a comment' in passing. Baseline 3 applies because the schema does the heavy lifting and the description adds no meaningful parameter semantics beyond that.

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: 'Permanently delete a comment.' The verb 'delete' and resource 'comment' are specific, and the emphasis on permanence distinguishes it from any plausible update or list operation. It is unambiguous and distinct from sibling tools like update_comment or add_comment.

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

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

The description gives clear context for when to use this tool: it is for permanently deleting a comment, with the caveat that only the author or an admin may do so. This effectively tells the agent who can use it and implies that unauthorized users should not attempt it. It does not explicitly exclude alternatives, but the sibling tools are clearly different 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?

The description goes well beyond the annotations. While annotations already indicate destructive intent (destructiveHint=true), the description adds critical behavioral details: the cascade to all child pages and the irreversibility ('There is no undo via the API'). This provides essential risk context for an agent.

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

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

The description is two concise sentences that front-load the primary action ('Permanently delete a page') and include a critical warning. Every sentence provides necessary information, and there is no wasted text.

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

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

For a simple delete tool with one parameter and no output schema, the description is nearly complete. It covers the key caveats (cascade and irreversibility) but omits any mention of what the API returns on success or permission requirements. This minor gap is acceptable given the simplicity of the operation.

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 already covers 100% of the parameter documentation, including the description for 'page' as a UUID or path. The tool description itself does not add additional meaning about the parameter, so the high schema coverage gives a baseline of 3.

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: 'Permanently delete a page.' It uses a specific verb and resource, and it distinguishes this from sibling tools like update_page or create_page. The warning about cascading deletion further clarifies the scope of the operation.

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

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

The description implies usage by saying what it does ('Permanently delete a page'), but it does not explicitly state when to use it versus alternatives or when not to use it. There are no exclusions or alternative tool references, making the guidance minimal.

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 set readOnlyHint=true, and the description adds valuable behavioral detail: the page carries comment metrics, images are returned as viewable blocks (with a tradeoff of being large and costly), and children are returned without content. This goes beyond the safety signal and explains what the response will look like.

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

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

The description is front-loaded with the main purpose, then efficiently explains each flag in relation to concrete scenarios. Every sentence provides operational value; there is no filler or redundancy.

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

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

For a read-only tool with no output schema, it covers the core return values (Markdown, version, comment counts), explains the optional includes, and warns about size implications. Nothing essential is missing for an agent to call 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 coverage is 100%, so the baseline is 3. The description enhances each optional flag with use-case context (e.g., 'folder' pages for include_children, 'SEE a screenshot' for include_images), elevating it above the schema alone without duplicating the page parameter's format.

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

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

The description opens with 'Read a page including its full Markdown content and current version number,' which states a specific verb and resource. This clearly distinguishes it from siblings like list_pages (which lists metadata) and search_docs (which searches).

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

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

It offers clear contextual guidance: include_comments when comment_count > 0, include_children for folder pages, include_images for visual content. It does not explicitly name alternative tools or exclusion conditions, so it stops short of a 5.

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

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

The description richly elaborates on idempotency beyond the idempotentHint annotation: pages matched by source path, created/reused/updated counts in response, default keep-content behavior, overwrite_existing re-sync, and fallback title rules (first # H1, then file name). No contradictions with annotations.

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

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

The description is well-structured: core purpose first, then format details, idempotency, alternative tool, and token nuance. It is longer than average but every sentence adds necessary information for a complex import tool 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?

Despite having no output schema, the description discloses response counts (created/reused/updated) and covers all key behaviors: file matching, hierarchy construction, title fallback, overwrite policy, parent nesting, and token scope. It is fully complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds substantial meaning: the {path, content} object format, path as relative file path, folder-to-hierarchy behavior, special index.md/README.md role, parent_page nesting, overwrite_existing semantics, and space omission for scoped tokens. This goes far beyond the schema's field comments.

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 ('Import') and resource ('a folder of Markdown files') plus the core mechanism ('folder structure becomes the page hierarchy'). It clearly distinguishes from sibling tools, especially by contrasting with bulk_create_pages later in the description.

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

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

It provides explicit when-to-use scenarios (Obsidian vault, Notion export, docs/ folder), explicitly names an alternative ('Use bulk_create_pages instead when you want to specify the page tree explicitly'), and explains re-running/chunking semantics for large imports.

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

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

With readOnlyHint=true already present, the description adds value by disclosing that comments are threaded and listing exact returned fields (id, content, author, parent). It does not mention pagination or sorting, but for a simple read-only list this is sufficient.

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

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

The description is compact, with the first sentence stating action and outputs, the second giving the primary use case, and a parenthetical noting the alternative. Every sentence is purposeful 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?

For a simple 1-parameter, read-only list tool with no output schema, the description provides enough context: return fields, threading, and how it fits with update/delete operations. It is complete for efficient selection and 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 input schema already fully describes the 'page' parameter, including two acceptable formats (UUID or path). The description does not add meaning beyond restating that comments are on a page, so the baseline of 3 applies.

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 lists threaded comments on a page and specifies the return fields (id, content, author, parent). It distinguishes this tool from get_page with include_comments, which returns the same thread alongside page 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 says to use this tool to find a comment's id before update_comment or delete_comment, and it notes the get_page alternative. This gives clear when-to-use guidance and differentiates from sibling 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?

While the readOnlyHint annotation covers safety, the description adds valuable behavioral details: content is omitted in the tree, comment counts are included for pages with discussions, and comments do not affect updated_at, requiring last_comment_at for spotting new replies. It also discloses token-scoping behavior. These go beyond the annotation's basic read-only declaration.

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

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

The description is three concise sentences, front-loading the main purpose, and every sentence adds meaningful information (purpose, content omission, comment metadata behavior, token guidance). 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 simple tool with one optional parameter, good annotations, and no output schema, the description covers the essential aspects: what it returns (tree), what is excluded (content), relevant metadata (comment counts), and token-specific usage. It is complete and self-sufficient for an agent to use correctly.

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

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

The schema already documents the optional 'space' parameter with 100% coverage, so the baseline is 3. The description adds extra semantic value by clarifying that omitting 'space' with a space-scoped token uses the token's space, which is not fully explicit in the schema description.

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

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

The description states a specific action: 'List the pages in a space as a tree' with a clear resource and output format. It also distinguishes itself from get_page ('use get_page to read a page'), making its purpose unambiguous among sibling tools.

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

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

The description explains when to use this tool (to list pages in a space) and explicitly points to an alternative (get_page for reading page content). It also gives context-specific guidance on omitting the 'space' parameter when using a space-scoped token. However, it does not mention exclusions or other alternatives like search_docs.

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, indicating a safe read operation. The description adds the workspace scoping but does not disclose additional behavioral traits like pagination, filtering, or access limitations. It does not contradict 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 a single concise sentence that gets straight to the point with no filler. It is front-loaded with the verb and resource.

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 read-only tool with one well-documented parameter and no output schema, the description is nearly sufficient. It states exactly what the tool returns, though it could optionally mention whether all spaces are listed or only those accessible to the user.

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

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

Schema description coverage is 100% for the single workspace parameter, so the description does not need to compensate. The description's phrase 'in a workspace' aligns with the schema but adds no extra meaning beyond what the parameter description already 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 action ('List') and the resource ('spaces') within a specific scope ('in a workspace'). This distinguishes it from sibling tools like list_workspaces and list_pages, which target different 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?

The description implies usage: to list spaces, you need a workspace. However, it does not explicitly mention when to use this tool over alternatives or any exclusions. The context is minimal but sufficient for a straightforward listing 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?

The annotations already declare readOnlyHint=true and openWorldHint=false, so the safe read nature is known. The description adds the permission scoping ('the user can access') and the hierarchy context, which is useful but not extensive. 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 two short sentences, front-loaded with the primary purpose, and the second sentence provides valuable hierarchical context without any 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?

For a simple read-only list tool with no parameters and no output schema, the description sufficiently explains what it does and the context of the returned items. The annotations cover the safety profile, and the hierarchy explanation completes the picture.

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, and the schema coverage is trivially 100%. The description doesn't need to add parameter details. Baseline for 0 params is 4, and no further info is required.

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 'List' and the resource 'AgentDocs workspaces', and further specifies the scope as those the user can access. This distinguishes it from sibling tools like list_spaces and list_pages, which operate on lower-level 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?

The description provides clear context by explaining the workspace-spaces-pages hierarchy, implying this tool is for top-level navigation. It does not explicitly state when not to use it or name alternatives, but the hierarchical context effectively guides the agent toward the correct usage.

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

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

Beyond the readOnlyHint=true annotation, the description adds a useful behavioral detail: 'Matches in the returned content_preview are delimited with << >> markers.' This informs the agent about output formatting, which is not present in annotations or schema. It does not mention potential rate limits or error cases, but the added marker convention provides meaningful transparency for a read-only search tool.

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

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

The description is exactly two sentences. The first sentence front-loads the core purpose with action and scope; the second adds a concrete output detail and an explicit alternative. Every word earns its place with no redundancy or fluff.

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

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

Given the tool's simplicity (2 required parameters, no output schema), the description covers everything essential: the search scope (all pages in a workspace), the result marker convention, and the guidance to use semantic_search for natural-language questions. This is sufficient for an agent to 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?

The input schema already documents both parameters with descriptions: 'Search terms' for query and 'Workspace UUID or workspace slug' for workspace. The tool description does not add any additional parameter semantics beyond what the schema provides. With 100% schema coverage, a baseline score of 3 is appropriate.

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

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

The description states exactly what the tool does: 'Full-text (keyword) search across all pages in a workspace.' It uses a specific verb ('search') and resource ('all pages in a workspace'), and explicitly distinguishes itself from the sibling semantic_search by noting when to prefer that alternative. This makes the purpose unmistakable.

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

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

The description provides explicit usage guidance: it identifies the tool as a keyword/full-text search and directly states 'For natural-language questions, prefer semantic_search,' naming the alternative and the condition for its use. This clearly tells the agent when to choose this tool versus a sibling.

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 only declare readOnlyHint=true and openWorldHint=false. The description adds important behavioral traits: pages are embedded automatically after each save, a Pro workspace is required, and the response mode can be 'semantic' or 'fulltext_fallback' depending on configuration. These go well beyond the structured annotations and help the agent anticipate variable responses.

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

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

Three sentences, each carrying distinct information: core purpose, embedding behavior, and configuration-dependent response. No redundancy, no filler; the description is front-loaded with the primary use case.

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?

Since there is no output schema, the description reasonably summarizes what is returned ('most relevant pages ranked by similarity') and explains the response mode. It omits details like result count or pagination, but for a two-parameter, read-only search tool this is sufficient. It also covers the Pro requirement and fallback, making the tool's behavior fairly predictable.

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 already covers both parameters at 100%, so the description's job is to add nuance. It provides an example query and emphasizes 'by meaning' to clarify the query intent, which is a meaningful addition to the schema's terse 'natural-language question' description. The workspace parameter isn't elaborated further, but the schema already handles it.

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

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

The description opens with 'Search a workspace by meaning, not keywords', which is a specific verb+resource+method that clearly distinguishes it from keyword-based siblings like search_docs. The example query and 'ranked by similarity' further pin down the semantic nature.

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

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

It contrasts with keyword search ('not keywords') to signal when semantic search is appropriate, and states a prerequisite ('Requires a Pro workspace'). The fallback explanation ('fulltext_fallback') also gives context for when results may be returned even without semantic configuration. However, it never explicitly names an alternative tool, so it doesn't fully reach a 5.

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

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

Annotations are all false, so the description carries the behavioral disclosure. It reveals the public-access nature of the created link and differentiates the two returned URL formats. It does not cover link revocation or expiration details, but the core side effect (creating a public share) is disclosed.

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

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

A single, front-loaded sentence that efficiently states the action, the outcome, and the return types. No filler.

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

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

Given the simple 2-parameter tool with no output schema, the description sufficiently explains the resource (page), the access model (public link), and the return values (web URL and raw-Markdown URL). It omits details like link expiration behavior, but the schema covers that and the description remains complete 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 coverage is 100%, with both parameters described in the schema. The description adds minimal parameter-specific meaning beyond the schema, only reinforcing that a page is shared and that two URL types are produced.

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 'Create a public magic link for a page' with a specific verb and resource. It clearly distinguishes from sibling tools like create_page by focusing on sharing with unauthenticated readers.

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 notes the link allows unauthenticated access ('anyone with the link can read it without logging in') and that the raw-Markdown URL is ideal for agents, giving clear usage context. Does not explicitly name alternatives or exclusions, but the sharing use case is well implied.

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

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

Annotations already mark destructiveHint=true, so the write nature is known. The description adds valuable context about authorization (author/admin only) and the 'at least one of' rule, which are not inferable from annotations alone. 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 two concise sentences, front-loaded with the core purpose, followed by the key constraint. Every word contributes value with no fluff or repetition of schema details.

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

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

The tool has no output schema, but the description covers its purpose, permissions, and parameter requirements. It omits return value details, but for a simple update operation this is not a significant gap. Annotations and schema fill the remaining 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 coverage is 100%, so parameters are already well-documented. The description adds the important constraint that content and resolved are optional individually but at least one must be provided—this is not enforced by the JSON schema and is essential for correct 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 uses a specific verb ('Edit') and resource ('a comment') and clearly defines the two actions: updating the body and/or marking the thread resolved. This clearly distinguishes it from sibling tools like add_comment and delete_comment.

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

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

It provides a clear usage constraint with the author/admin restriction and states the requirement to provide at least one of content/resolved. While it doesn't explicitly discuss alternatives, the sibling tools make the update role obvious, and the permission note gives practical usage context.

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

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

Annotations already flag destructiveHint and readOnlyHint, but the description adds valuable context: every update creates a restorable version, and expected_version can reject stale updates. This goes beyond what annotations alone convey.

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

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

The description is two concise sentences. The first front-loads the core purpose; the second adds key behavioral details. 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?

For a moderately complex update tool with 4 parameters and no output schema, the description covers purpose, versioning behavior, and concurrency. It omits prerequisites like the page existing, but that is implied and covered by the 'page' parameter 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?

The schema has 100% parameter coverage, so the baseline is 3. The description enhances this by explaining expected_version's role in preventing concurrent overwrites, adding meaning beyond the schema's field-level 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 'Update a page's title and/or content' with a specific verb and resource, distinguishing it from sibling tools like create_page, append_to_page, and delete_page.

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

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

The description implies usage for editing existing pages but does not explicitly mention when to use this tool versus alternatives like create_page or append_to_page. It does provide contextual detail about versioning and concurrency control, which informs 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?

Beyond the annotations (readOnlyHint, etc.), the description reveals key behaviors: format detection from bytes, SVG rejection due to script-injection risk, quota impact, and the limitation that a viewed image cannot be re-encoded. These are not evident from annotations and enrich the agent's understanding.

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 excessively verbose, repeating parameter details already present in the schema and embedding extensive explanatory text. It could be condensed to the essential purpose and critical usage notes without losing clarity. The structure is also messy, mixing acceptance criteria and guidance in a single long paragraph.

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

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

The description covers all necessary aspects: purpose, usage context, parameter semantics, behavioral side effects, and limitations. It even hints at the return format ('get back the Markdown'). Given the lack of output schema, it provides sufficient context for an agent to 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?

Although the schema already describes each parameter (100% coverage), the description adds semantic nuance: it explains why 'path' is preferred ('the bytes never enter the conversation'), that 'data' cannot be derived from a viewed image, and that 'source_url' must be publicly reachable. This goes beyond the schema's literal description and helps correct usage.

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

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

The description states a specific verb ('Attach') and resource ('an image to a space'), and clarifies the output ('get back the Markdown'). It clearly distinguishes the tool's purpose from siblings, as no other sibling handles image upload.

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

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

The description provides explicit guidance on when to use it ('Use this to put screenshots and diagrams') and how to supply the image, including preferred methods (path over data) and constraints (e.g., 'If you can only SEE an image... you cannot re-encode it'). It implicitly explains when not to use (e.g., when you only have a view, not a file).

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 the description adds meaningful context about credential scope and how it affects page tools. This goes beyond the simple read-only flag, but it doesn't disclose potential edge cases or response details; still, for a simple whoami operation this is sufficient.

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

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

The description is two sentences long, with the core purpose front-loaded and no wasted words. Every sentence earns its place, and the structure is logical: first states what it does, then gives actionable usage advice.

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

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

For a tool with no parameters and a read-only annotation, the description covers the essential context: what it identifies and how it relates to credential scope. It does not describe the return format, but given the low complexity and clear purpose, the description is nearly complete. A slight gap is the lack of explicit mention of response 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?

The tool has zero parameters, so the schema requires no explanation. The description correctly focuses on the tool's behavior rather than parameters. The baseline for 0 params is 4, and no additional parameter semantics are 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 the tool's purpose with a specific verb and resource: 'Identify the authenticated AgentDocs user and credential scope.' It also distinguishes itself from sibling tools by positioning it as a preflight step ('Call this first'), which is unique among the listed page 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?

The description explicitly provides usage timing ('Call this first') and explains why it matters relative to space-scoped credentials. However, it does not explicitly mention when not to use it or name alternatives, though the context makes those clear. This is strong guidance but not a full 5.

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