tela

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the tool is a non-destructive mutation. The description adds context about the anchoring mechanism and the editor+ permission. It does not contradict annotations and provides useful behavioral context beyond what annotations offer.

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, front-loaded sentence that states the core purpose without any extraneous words. It effectively communicates the essential information.

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

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

Given the tool's complexity (4 params, 1 nested object, output schema exists), the description provides the high-level goal and anchoring detail. It does not cover idempotency behavior or error states, but the schema and output schema fill some gaps. It is mostly complete for a mutation 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%, with each parameter described in the input schema. The description summarizes the anchor object as a '{prefix, exact, suffix} text triplet' but adds no new semantic meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description uses specific verbs and resources: 'Attach a root comment to a page, anchored by a {prefix, exact, suffix} text triplet (editor+).' It clearly states the action, the target, and the anchoring mechanism, distinguishing it from any sibling tools (no other comment tools exist among 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?

The description implies usage by stating the anchoring requirement and the '(editor+)' permission hint, but it does not explicitly state when to use this tool versus alternatives. There are no other comment-related sibling tools, so no direct comparison is available, but guidance on conditions or exclusions is missing.

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, so this is a safe read operation. The description adds valuable context by listing the specific fields returned (owner, output space, schedule, source count, latest-run summary, can_manage), which goes beyond the annotation to explain what the output contains.

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

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

The description consists of two efficient sentences. The first sentence states the action and scope, and the second details the fields and usage recommendations. Every word is essential, and there is no redundancy or filler.

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

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

Given the tool has no parameters and an output schema exists, the description adequately covers the purpose and usage. It even mentions the key output fields and how to use the results. The reference to atlas_run provides helpful context. No gaps are apparent.

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 no parameters, and schema description coverage is 100% (vacuously). The description does not need to add parameter semantics, but it provides meaningful information about the output, which compensates for the lack of parameters. Baseline for 0 parameters is 4.

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

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

The description clearly states that the tool lists atlas doc-generation projects visible to the user, including personal and org projects. It specifies the fields each project carries and identifies the primary use case of finding a project_id for atlas_run, distinguishing it from sibling tools like atlas_run and atlas_run_status.

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 advises to 'Start here to find a project_id for atlas_run, or to read coverage health at a glance,' providing clear context for when to use this tool. It implies that this tool is the precursor to atlas_run, but does not explicitly state when not to use it or list alternatives.

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

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

The description discloses behavioral traits beyond annotations: it rewrites generated subtree, spends LLM budget, creates output space on first run, and returns run_ids per source. Annotations do not contradict this description (readOnlyHint=false, destructiveHint=false is consistent with a regeneration that is not permanently destructive).

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 with critical information front-loaded. Every clause adds value: management-level caveat, LLM budget consumption, return value, error condition. No wasted words.

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

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

Given the tool's complexity (mutation, budget consumption, multiple return objects), the description covers prerequisites, effects, return format (run_ids), polling instruction, and a specific error. The presence of an output schema is noted, but the description already explains what the tool returns.

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 single parameter project_id with 100% description coverage. The description adds useful context that project_id comes from atlas_list_projects, which aids the agent in sourcing the value.

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

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

The description clearly states the tool triggers a full doc-generation run for every source in an atlas project. It uses specific verbs ('trigger', 're-ingest', 'regenerate', 're-audit') and distinguishes from siblings like atlas_run_status and atlas_list_projects.

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 the operation is management-level and requires project_id from atlas_list_projects. It also notes that it spends LLM budget and returns a 503 if no embedder/LLM is configured. However, it does not explicitly state when not to use it or suggest alternatives beyond atlas_run_status.

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=true, destructiveHint=false. The description adds details on returned data (status, stage, coverage metrics). No contradiction; it supplements annotations with specific behavioral context.

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

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

Single paragraph, dense but efficient. Lists key outputs without unnecessary fluff. Could be slightly more structured, but overall 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 has an output schema (context indicates present), the description need not explain return values. It already describes what the tool returns sufficiently for a simple read 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?

Schema coverage is 100% for the single parameter, so baseline is 3. The description does not add meaning beyond the schema's own description of run_id, thus no extra value.

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

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

The description clearly states the tool reads an atlas run's status and coverage by run_id. It lists specific output fields and distinguishes from sibling atlas_run by indicating it reads rather than starts a run.

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 'Use to follow a run started by atlas_run to completion and judge whether the docs are complete.' This gives a clear use case. While it doesn't mention when not to use, the context is sufficient.

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

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

Annotations already provide idempotentHint=true and readOnlyHint=false. The description adds that the tool returns a serve URL and markdown, and that it's for hosts that couldn't read the PUT response. No contradictions; adds valuable context beyond annotations.

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

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

Two sentences, front-loaded with the core purpose and usage condition. Every sentence adds value: first explains the action and return, second adds permission and next steps. 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 entire workflow: when to call (after PUT), what it returns, permission level, and how to use the result. An output schema exists (not shown) which handles return structure. For a simple confirmation tool, this is fully complete.

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

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

The single parameter upload_id is fully described in the schema as 'the upload_id from request_attachment_upload'. The description does not add extra meaning, so with 100% schema coverage, baseline 3 is appropriate.

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

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

The description clearly states the tool confirms an upload after bytes are PUT, returning the serve URL and markdown. It distinguishes itself from siblings like request_attachment_upload and upload_attachment by specifying the exact step in the upload workflow.

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 it's for 'Editor+' users and guides to use output with update_page/patch_page. It implies the prerequisite of having PUT bytes to the URL from request_attachment_upload, but does not explicitly exclude alternatives or mention when not to use.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description explains creation behavior, markdown support, backlinking, idempotency key for safe retries, and special handling for decks and sheets. 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 quite long but front-loaded with the core action. Every sentence serves a purpose, given the tool's complexity and need to guide special content types. Could be slightly trimmed, but overall well-structured and informative.

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

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

Given the tool's complexity (rich content, multiple output formats) and the presence of an output schema, the description is remarkably complete. It covers all major features, references external guides, and handles edge cases (idempotency). No gaps identified.

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

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

With 100% schema description coverage, the description still adds value by explaining the purpose of body (markdown), props (frontmatter, including deck and sheet properties), and idempotency_key (safe retries). It elaborates on how deck=true and sheet=true trigger special formatting, which is not in 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 'Create a page in a space' with specific verb and resource. It distinguishes from sibling tools like update_page, delete_page, and patch_page by detailing how this tool creates new pages. The mention of markdown body, special links, and rich block palette further clarifies its purpose.

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

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

The description provides extensive guidance on when to use this tool for creating ordinary pages, and when to instead use deck_authoring_guide or sheet_authoring_guide for presentations or spreadsheets. It advises against simple text walls and for using rich blocks. This clearly directs the agent to appropriate 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 indicate a mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds behavioral context: caller becomes owner, slug is derived from name. It does not mention idempotency behavior or error conditions, which are partially covered by the idempotency_key parameter schema.

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 extremely concise with two sentences, no fluff, and front-loads the purpose. Every sentence adds value.

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

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

Given the 4 parameters, full schema coverage, and the existence of an output schema (not shown), the description is adequate but could be more complete. It lacks details on idempotency behavior and error handling, but for a simple creation tool, it sufficiently covers the essentials.

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% and all parameters are described in the schema. The description repeats the slug derivation info from the schema, adding no new meaning. The idempotency_key parameter is not mentioned in the description, so the description adds minimal value beyond the schema.

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

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

The description clearly states the action (create), the resource (space), and adds specific details: the caller becomes owner and slug derivation from name. This effectively distinguishes it from siblings like delete_space or update_space.

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 does not provide explicit guidance on when to use this tool versus alternatives such as create_page or update_space. However, the context of creating a space is clear, and the ownership/slug details offer implicit direction.

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

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

Description adds significant context beyond annotations: it specifies the output format (markdown), the content structure (layouts, fields, components, style variants), and the sub-fetch pattern for optional modules. Annotations already indicate read-only, and description aligns perfectly with no contradictions.

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

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

Two sentences, both essential. First sentence describes what is returned (the guide content). Second sentence provides critical usage advice and explains the module parameter. No unnecessary words; information is front-loaded and well-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?

Given the availability of an output schema and the straightforward nature of a guide-retrieval tool, the description covers all needed aspects: what it returns, when to use it, and how to use the optional parameter. It is complete for the agent to correctly invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining that the 'module' parameter fetches extra guidance when applicable, and gives examples like 'branding, imagery'. This enhances the agent's understanding of how to use the parameter effectively.

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?

States clearly that the tool returns the full deck authoring guide as markdown, covering layouts, fields, components, and style variants. The verb 'Return' and resource 'deck authoring guide' are specific, and the scope is well-defined. Implicitly distinguishes from sibling 'sheet_authoring_guide' by focusing on decks.

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 instructs to read this FIRST when creating or editing a deck to avoid guessing. Also explains when to call again with the module parameter for extra guidance. However, it does not explicitly state when NOT to use the tool or list alternatives, leaving 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?

Discloses soft-delete nature and role requirement, which adds context beyond annotations. Does not contradict annotations; destructiveHint=true matches.

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

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

Two sentences, no fluff, front-loaded with key action and constraints.

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

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

With output schema present, no need to describe returns. Covers action, role, id source, soft-delete, and critical behavioral note about page body. 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 already provides 100% coverage with clear descriptions for both parameters. The description reinforces id source but adds minimal extra 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 detaches a file from a page by attachment id, differentiates from editing page body, and mentions role requirement and id source. It effectively distinguishes from siblings like 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 explains when to use (detach by id) and explicitly warns against using it for inline embeds, directing to update_page/patch_page. It could mention more alternatives but is sufficient.

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

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

Annotations already mark as destructive. The description adds important context: backlinks are preserved with the last-known title, which is beyond what annotations provide.

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

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

Two concise sentences, front-loaded with the main action and permission level. No unnecessary words.

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

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

For a simple destructive tool with one parameter and an output schema, the description covers the essential behavior including backlink preservation, making it complete.

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

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

Schema coverage is 100%, and the description adds no extra meaning beyond the schema's description of the 'id' parameter. Baseline score 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 action ('Delete') and the resource ('page'), specifies the required permission level ('editor+'), and distinguishes from sibling tools like delete_space or delete_attachment.

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

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

It mentions who can use it ('editor+') and what happens to backlinks, but does not provide explicit guidance on when to use this tool versus alternatives like move_page or archive.

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

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

Adds significant context beyond annotations: cascading deletion of all associated content, owner-only restriction, irreversibility. No contradiction with annotations (destructiveHint=true matches 'Irreversible').

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 with no wasted words. Front-loaded with core action and scope.

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, effects, and constraints. Output schema exists (from context) so return values are covered there. Could be slightly more complete with a note on authorization, but already mentions 'Owner only'.

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 description 'space id to delete (cascades)'. Description echoes cascading but adds no new parameter-level detail. Baseline 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?

Clearly states it deletes a space and all its contents (pages, comments, revisions, share links), distinguishing it from sibling tools like delete_page or delete_attachment.

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

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

Mentions 'Owner only' (prerequisite) and 'Irreversible' (warning). Lacks explicit comparison to alternatives like delete_page for partial deletion, but the cascading nature implies when to use this over other delete 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?

Discloses atomicity of batch operations, error handling (bad ref/range/sheet rejected with fixable error), and return behavior (returns updated sheet with formulas computed). Adds value beyond annotations which only indicate non-readonly, non-destructive, and non-open-world. Also explains that it prevents grid corruption.

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

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

Description is dense but well-structured. First sentence states purpose and recommendation. Followed by explanations of operation types and behavior. Could be slightly more concise, but every sentence adds value.

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

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

Given the complexity (nested objects, 3 params, output schema exists), the description is highly complete: covers all operation types, atomicity, error handling, return value, and references external guide. No gaps identified.

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

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

Schema coverage is 100%, but description adds rich semantic detail: explains the 'op' and 'ops' parameters, lists all operation kinds with syntax examples (setCells, insertRows, etc.), and explains optional 'sheet' parameter within ops. This goes far beyond the schema.

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

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

The description clearly states the tool's purpose: 'Make a STRUCTURED edit to a sheet (a sheet=true page), editor+.' It specifies the verb (edit), resource (sheet), and scope (structured). It also distinguishes from the sibling tool 'update_page' by explaining why to prefer this for sheets.

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 to prefer this over update_page for sheets, with a rationale. Mentions permission requirement ('editor+') and refers to sheet_authoring_guide for full reference. Could be more specific about when not to use, but provides clear guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is clear. Description adds that it retrieves 'full text', which is a behavioral trait beyond the schema or annotations. No further disclosure of rate limits or authentication needed given the tool's simplicity.

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: first sentence is clear and concise. The second sentence ('The ChatGPT Deep Research fetch tool.') is somewhat redundant and adds little value, but does not harm clarity. Efficient for a simple 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 read-only tool with one parameter, clear annotations, and an output schema (assumed), the description adequately covers what the tool does and where the input comes from. No missing information that would hinder correct invocation.

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

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

Schema description coverage is 100%: the single parameter 'id' is already described as 'page id, as returned by search results'. The description repeats this information without adding new meaning. Baseline of 3 is appropriate.

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

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

Clearly states it fetches the full text of a tela page by ID, distinguishing it from siblings like get_page or list_pages. The mention of 'full text' and 'id comes from a search result' specifies the scope and origin of input.

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?

Implies use after search results (id comes from search), but does not explicitly state when to use this tool versus alternatives like get_page or read_chunk. No exclusions or when-not-to-use guidance provided.

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

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

Annotations indicate readOnlyHint=true and destructiveHint=false, which align with the description's implied non-destructive behavior. The description adds detail: pairs are identified by chunk-level cosine similarity, threshold range, and default value, going beyond annotations to explain the detection mechanism.

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: first defines purpose and result, second explains parameters. No wasted words, front-loaded with key information. Highly 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?

Given that an output schema exists (though not shown), the description need not explain return values. It covers purpose, usage context, and parameter semantics sufficiently for an agent to decide when and how to invoke it. The context signals (high schema coverage, no required params) support 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?

Input schema has 100% description coverage, so baseline is 3. The description adds value by explaining that 'threshold' controls chunk-level similarity (range 0..1, default 0.92) and 'space_id' restricts to one space. However, 'limit' is not mentioned in the description, though schema provides default (50). Overall, adds meaningful context beyond schema.

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

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

The description clearly states the tool finds 'near-duplicate page PAIRS' for wiki hygiene, specifying the result type (pairs) and use case (merge/redirect candidates). It distinguishes from sibling tools like 'related_pages' or 'search' by focusing on near-identical passages.

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 the tool ('wiki hygiene', 'real merge/redirect candidates') and provides optional parameters to restrict scope (space_id, threshold). However, it does not explicitly state when not to use it or mention alternatives among siblings.

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

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

The description discloses important behavioral traits beyond annotations: potential 503 errors if image generation is not configured, long generation times (20s to minutes), and the instruction to reference the image by path to avoid regeneration. Annotations show readOnlyHint=false, so this is consistent with a generative 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 fairly long but every sentence adds value. It is front-loaded with the main action and includes important caveats. Minor redundancy could be trimmed, but overall it is well-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?

Given the complexity (7 parameters, output schema exists), the description is complete. It explains return values (serve URL + snippet), gives usage instructions, and addresses potential issues. It complements the output schema well.

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?

Even though schema coverage is 100%, the description adds significant meaning: for the 'steps' parameter it gives guidance on typical values ('~10 for hero/cover, ~4 for incidental texture'), and for 'prompt' it advises to append 'no text, no letters, no words' for FLUX models. This goes beyond the basic schema descriptions.

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

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

The description clearly states the tool's purpose: generate an image from a prompt and attach it to a deck page. It specifies the resource (image), the action (generate and attach), and the context (deck page). This distinguishes it from siblings like 'treat_deck_image' which likely modifes an existing image.

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: 'Read the imagery module first... most slides need NO image — use it for atmosphere/concept/focal only, reuse ONE background...' It also warns about potential unavailability (503). It does not explicitly list alternatives but the context is clear enough.

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

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

The description goes beyond the readOnlyHint annotation by detailing the epistemic block with trust signals (freshness, provenance, corroboration). It advises on how to weigh pages (prefer fresh, corroborated, human-reviewed; treat stale/disputed as lower-confidence). 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 a single, well-structured paragraph that front-loads the main purpose and then adds key behavioral and parameter details. Every sentence provides value; no redundancy or wasted words.

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

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

Given the existence of an output schema, the description adequately covers the return content (markdown body, metadata, epistemic block) and parameter details. It could mention that the page ID must exist, but overall it's complete for a read 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?

With 100% schema coverage, the description adds significant meaning beyond the schema: explains that 'full' returns markdown body, 'map' returns heading outline (cheap, with paths for patch_page), and 'values' returns computed spreadsheet for sheet pages. This clarifies usage context.

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

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

The description clearly states the tool retrieves the full markdown body and metadata for a numeric page ID. It specifies the resource (page by ID) and the action (get), distinguishing it from sibling tools like list_pages or get_space.

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 guidance on when to use each format parameter (full, map, values) and notes that map is cheap and that values is for sheet pages. However, it does not explicitly compare this tool to siblings or state when to use get_page over other read 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=true and destructiveHint=false, so the safety profile is clear. The description adds value by specifying exactly which fields are returned (id, name, slug), going beyond the annotation alone.

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

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

The description is a single, well-structured sentence with no wasted words. It front-loads the key purpose and includes all necessary information.

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

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

Given the tool's simplicity, full schema documentation, annotations, and output schema, the description is complete. It covers purpose, scope, and return value without needing more detail.

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%, and the only parameter 'id' is well-described in the schema as 'space id'. The description does not add further meaning beyond the schema, so baseline of 3 is appropriate.

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

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

The description clearly states 'Fetch a single space's metadata (id, name, slug) by id.' It specifies the verb (fetch), resource (space), scope (single by id), and what fields are returned. This distinguishes it from list_spaces and other 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 explicitly says 'by id', making it clear the tool should only be used when you have a specific space ID. It implicitly excludes listing multiple spaces or fetching by other criteria, which is sufficient for a simple lookup tool.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false. The description adds that it exposes user questions (privacy concern) and is admin-only, which is useful behavioral context beyond annotations. No contradiction.

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

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

Two sentences: first defines the tool's core value, second adds access and parameter context. No wasted words. Front-loaded with the most important 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?

With an output schema present, the description need not detail return values. It explains purpose, access restrictions, and parameter behavior adequately. It doesn't explicitly mention sorting (most-asked implies decreasing frequency) but that is reasonable.

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 reinforces the meaning of since_days as a time window and implies that limit caps results. This adds value by framing the parameters in the tool's purpose.

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 returns the most-asked unanswered questions from the 'ask your docs' feature, framing it as a content roadmap. It distinguishes from sibling tools like 'search' or 'research' by focusing on gaps. The 'Instance-admin only' and 'since_days' details add clarity.

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 specifies that the tool is for admins only and that it exposes users' questions, implying usage for identifying content gaps. It mentions the optional since_days parameter but does not explicitly compare to siblings or state when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, confirming safety. The description adds that it returns 'structured issues per slide', providing useful behavioral context beyond annotations.

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

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

Two sentences, no filler, with essential information front-loaded. Every sentence contributes value.

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

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

Given the low complexity (1 param, output schema present), the description covers purpose, timing, and links to related tool. It is complete without over-explaining.

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 the single 'id' parameter already described in the schema. The description does not add extra meaning beyond the schema, meeting the baseline.

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

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

The description uses a specific verb ('Validate') and resource ('deck page's slides against the tahta theme contract'), clearly distinguishing from sibling tools like preview_deck and generate_deck_image.

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 ('Run after authoring/editing a deck to catch problems before presenting') and suggests an alternative tool (deck_authoring_guide) for more detailed schema information.

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. The description adds that it lists both uploads and rclone-synced files, and explains the 'embedded' field meaning. This adds value beyond annotations without contradiction.

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

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

Two-sentence description is concise, front-loaded with the core action, and includes all essential details without verbosity. Every sentence adds value.

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

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

Given output schema exists (not shown), description covers key aspects: file types listed and returned fields. No mention of pagination, but overall sufficient for a listing tool with good annotations.

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

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

Schema coverage is 100% with page_id described as 'page whose attachments to list'. Description does not add further semantics beyond what the schema provides, so baseline score 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 it lists files attached to a page, specifying both uploads and rclone-synced files, and enumerates the returned fields (name, mime, size, URLs, markdown snippet, embedded flag). This distinguishes it from sibling tools like upload_attachment, delete_attachment, etc.

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

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

The description implies usage for reading attachment info but does not explicitly state when to use this tool versus alternatives like upload_attachment or delete_attachment. No exclusions or context provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; description adds constraint on link types but no further 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, front-loaded sentence with no wasted words; appropriately concise for a simple 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?

Given simple tool with one parameter and existing output schema, description is sufficient; no need to detail return values as output schema exists.

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% and schema already describes page_id; description does not add additional meaning beyond what 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 it lists pages linking to a given page via specific link formats (wikilink and tela://page/{id}), distinguishing it from sibling tools like list_pages or related_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?

No explicit guidance on when to use this tool versus alternatives like search or related_pages; no exclusions or context provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds behavioral context about flat listing and hierarchical filtering via parent_id, which is useful beyond annotations.

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

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

Two sentences, front-loaded with purpose, no wasted words. Each sentence adds value.

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

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

Given two parameters, output schema exists, and annotations present, the description covers the essential behavior. Minor gap: doesn't explain the return format, but output schema handles that.

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

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

Schema description covers both parameters (100% coverage). Description adds meaning for parent_id: 'direct children' vs 'top-level pages', which clarifies optional behavior beyond schema text.

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 'Flat page listing in a space' with specific verb and resource. Distinguishes from siblings like get_page (single page) and list_spaces (spaces).

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 usage for parent_id ('for direct children, omit for top-level') but lacks explicit guidance on when to use this tool vs other list tools like list_attachments or list_backlinks.

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: active-only default, bearer token sensitivity, and required write-scoped key. Annotations already indicate readOnlyHint=true, so no contradiction.

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

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

Two sentences pack all essential information: purpose, output fields, default behavior, parameter usage, authentication requirement. No unnecessary words.

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

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

With output schema present, description covers purpose, usage, parameters, and behavioral nuances comprehensively. No gaps for an AI agent to resolve.

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 already describes both parameters with 100% coverage. Description mentions include_revoked implicitly but adds no new semantic value 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 it lists a page's public share links, enumerates the fields returned, and implicitly distinguishes from sibling tools like share_page and revoke_share by focusing on listing, not creating or revoking.

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 guidance on default behavior (active only) and how to include revoked links. Mentions need for a write-scoped key due to token sensitivity, but does not explicitly state when not to use or compare with 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=true and destructiveHint=false. The description adds that the listing is scoped to the API key's access (authorization context). It does not mention pagination, limits, or sort order, but the output schema likely handles return structure. The description adds minimal behavioral context beyond the annotations.

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

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

The description is a single sentence with no unnecessary words. It is front-loaded with the action and resource, and additional details are given in parentheses. Every word earns its place.

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

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

Given no parameters, rich annotations, and an output schema, the description is complete. It succinctly states the purpose and the data returned. No gaps are apparent for an agent to understand and invoke the tool correctly.

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

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

There are no parameters (0 params, 100% schema coverage). Per guidelines, 0 params baseline is 4. The description adds value by specifying that the tool returns id, name, slug, which is not required but helpful.

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 'List every space the API key can access (id, name, slug).' It clearly identifies the verb (List), resource (spaces), and scope (accessible to API key). The sibling tools include get_space (single), create_space, update_space, delete_space, so this tool is well-distinguished as a list 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 clearly indicates when to use: when you need a list of accessible spaces. It does not explicitly state when not to use, but the context of sibling tools (e.g., get_space for a specific space) provides implicit guidance. No alternative tools are named.

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

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

Annotations indicate idempotentHint=true, description adds permission requirement and parameter constraints. There is no contradiction with annotations. Description adds value beyond annotations.

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

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

Two sentences, each packed with essential information. Front-loaded with action and parameters, followed by permission and requirement. 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?

Covers operations, permissions, parameter requirements, and mutual exclusivity. Does not detail return value or errors, but output schema is present. Adequate for a tool with moderate 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 100%. Description explains each parameter's role (e.g., 'reparent (parent_id)') and notes mutual exclusivity between make_root and parent_id, adding meaning beyond schema.

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

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

Description clearly states the verb 'move' and the resource 'page'. It lists specific operations: reparent, detach, reorder, relocate. This distinguishes it from sibling tools like create_page, update_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?

Provides clear context: requires Editor+ permission in both source and target space, and states minimal parameter requirements. Does not explicitly list when to avoid or mention alternatives, but the context is sufficient.

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

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

Discloses that it 'never touches the rest of the document' and 'Snapshots a revision like any edit'. Annotations are minimal but description adds safety and revision context. Could mention idempotency more but schema covers that.

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 action and benefit. No wasted words. Jargon 'editor+' is acceptable in context.

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, prereqs, comparison to update_page, and behavioral guarantees. Output schema exists, so return info not needed. Sufficient for a well-described 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%, and description adds workflow context for 'target' (using get_page format:map). Clarifies 'content' can be omitted for delete. Lists operation options with effects.

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?

Explicitly states it 'surgically edit ONE section of a page instead of rewriting the whole body', clearly distinguishing from update_page. Verb 'patch' and resource 'page section' are precise.

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

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

Provides explicit when-to-use: 'Cheaper and safer than update_page on a long page'. Also gives prerequisite: 'First call get_page format:"map" to see the section paths'. No overlap with siblings.

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

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

The description discloses that renders are cached, a behavioral trait beyond the readOnlyHint annotation. It aligns with the annotations (readOnlyHint=true, destructiveHint=false), and adds context about the tool's non-destructive nature. No contradiction.

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

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

The description is extremely concise, comprising two sentences with no wasted words. The most critical information (purpose and usage) is front-loaded.

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

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

For a read-only preview tool, the description covers key aspects: purpose, parameter usage, and caching behavior. However, it does not specify the return format of the slide images (e.g., URLs or data URIs), which could be helpful for 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?

The description clarifies that slides are 1-based and that omitting them previews the first few frames, but this information is already present in the input schema's parameter description. No additional meaning is provided beyond the schema.

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

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

The description clearly states the tool renders a deck page to slide images for visual preview, distinguishing it from authoring blindly. It also differentiates from sibling tools like 'generate_deck_image' or 'lint_deck' by emphasizing the preview aspect.

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 the tool (to see how the deck looks) and how to use it (pass specific slides or omit for first few). However, it does not explicitly state when not to use it or suggest 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=true and destructiveHint=false. Description adds the return behavior (full section text, file chunk info with file_name, parent_page_id, download_url), which is transparent about what the tool returns.

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 action and resource, no redundant information. Every word adds value.

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

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

Given the simple parameter set and presence of an output schema, the description fully explains the purpose, return content, and context relative to sibling tools. No gaps.

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

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

Schema has 100% coverage with chunk_id described as 'chunk id from a research result'. Description adds meaning by specifying the source ('research' source) and the two use cases (page or file chunk), going 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?

Clearly states the tool fetches a chunk's full section text by chunk_id from a research source. Distinguishes its granularity (between research excerpt and get_page) and notes file chunk specifics, differentiating it from 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?

Provides context on when to use it by describing its granularity relative to other tools (research excerpt, get_page). Does not explicitly state when not to use, but the positioning is clear enough.

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

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

Annotations declare readOnlyHint=true and no destructive behavior; description adds that it uses stored vectors (no live embedder required), enhancing understanding of operational behavior.

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

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

Two sentences, each adding distinct value: first states purpose and ranking, second notes technical independence. No fluff.

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

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

For a simple tool with 2 parameters and an output schema, the description is complete: it defines the core function, ranking, and key aspect (no live embedder). No missing critical 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 coverage is 100% and both parameters (page_id, limit) are clearly described in the schema. Description adds no additional semantic detail beyond what 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?

Clearly states it finds semantically related pages ('see also'), ranked by similarity, explicitly distinguishing from explicit wikilinks/backlinks. The verb 'find' and resource 'related pages' are specific and unambiguous.

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

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

Provides context that no live embedder is needed (uses stored vectors), implying when to use it. It does not explicitly list alternatives but differentiates from backlink-based 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 indicate non-read-only and non-destructive behavior. The description adds that the URL is short-lived, the host must perform an outbound HTTP PUT, and the file bytes do not pass through the model context. 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 a single paragraph that efficiently conveys purpose, flow, conditions, and alternatives. It front-loads the key information. Could be slightly improved with clearer separation of steps, but it is concise overall.

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, the description covers the full workflow, prerequisites, alternatives, and integration with sibling tools (confirm_attachment_upload, update_page/patch_page). The existence of an output schema means return values need not be explained. Complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant additional parameter meaning beyond what the schema already provides. The schema descriptions are already clear.

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

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

The description clearly states the tool provides a short-lived signed PUT URL for uploading files without sending bytes through the model context. It specifies the use case (files over 5 MB or to avoid context bloat) and distinguishes it from the sibling tool upload_attachment.

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

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

Explicitly states when to use this tool (large files, context bloat avoidance) and when to use upload_attachment instead (if host cannot make outbound HTTP PUT). It also outlines the entire flow, including post-steps like calling confirm_attachment_upload or reading the PUT response.

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

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

Discloses output structure (context, sources, disagreements, low_confidence), that it pulls from pages and attached files, and that a configured embedder is required. No contradiction with readOnlyHint and destructiveHint annotations.

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

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

Well-structured: front-loads purpose, explains returns, guides agent on use, and lists alternatives. Every sentence adds value without redundancy.

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

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

Given the complexity (multiple output fields) and presence of output schema, the description fully explains what the tool returns and how to use it, including edge cases like embedder requirement.

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 adequate descriptions. The tool description adds behavioral context but does not significantly enhance parameter-specific meaning beyond the schema.

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

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

The description clearly states the tool answers a question or gathers context by meaning from the wiki, distinguishing it from siblings like 'search' (exact lookup) and 'read_chunk'/'get_page' (deeper reading).

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 says when to use (answer by meaning) and when not (exact lookup use 'search', deeper reading use 'read_chunk'/'get_page'), plus notes the embedder requirement.

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 as destructive and idempotent. The description adds that the link stops working immediately and that revoking an already-revoked link is a no-op, providing extra behavioral context beyond annotations.

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

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

The description is two sentences, all essential information is front-loaded. Every sentence adds value with no redundancy.

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

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

Given the single parameter and existence of an output schema, the description provides complete context: how to obtain the id, the immediate effect, and idempotency guarantee.

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%, with the parameter described as 'id of the share link to revoke (from list_shares)'. The tool description repeats this, adding no new meaning beyond what the schema 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 tool disables a public share link by its id, with the verb 'disable' and resource 'public share link'. It distinguishes from sibling tools like share_page by specifying that it revokes, not creates, shares.

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 specifies that ids come from list_shares and requires editor+ permissions, providing clear context. It does not explicitly mention when not to use or alternatives, but the context is sufficient.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. Description adds behavioral context: full-text search, always available, ranking and snippets. No contradictions.

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

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

Three sentences, front-loaded with purpose, no wasted words. Every sentence adds essential 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 read-only search tool with 3 params and an output schema, the description covers purpose, usage, behavioral traits, and parameter semantics fully. Agent can confidently invoke this 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% and schema descriptions are clear. Description enriches query parameter by specifying it can be an exact term/identifier/error string, adding value beyond schema.

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

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

Clearly states it performs keyword full-text lookup over title and body, returning ranked results with snippets. Distinguishes from sibling 'research' by noting it is for exact terms vs semantic meaning.

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

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

Explicitly tells when to use (find a page by name or exact term/error string) and when not to (use 'research' for topic meaning). Also notes it works without an embedder, setting availability expectations.

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

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

Discloses return values (url, id, token), effects of options (password gates, expires_at auto-expires, include_descendants shares subtree), and that each call creates a new link. Annotations are consistent and non-contradictory.

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

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

Well-structured with action, return, options, and lifecycle/alternatives. Every sentence is informative and concise, 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?

With output schema present, description still covers return values. Addresses all key aspects: what, how, options, lifecycle, and comparison to alternatives. Sufficient for agent to invoke correctly.

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

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

Schema coverage is 100%, but description adds meaningful explanations beyond schema descriptions: password as 'gate behind a passphrase', expires_at as 'auto-expire at this UTC', include_descendants as 'share the whole subtree'.

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?

Clear verb 'Mint' and resource 'public share link for a page'. Distinguishes from siblings list_shares and revoke_share, and from space visibility setting for whole space.

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 each call mints a new link, recommends list_shares to see existing ones, and revoke_share to disable. Also contrasts with publishing a whole space via visibility setting.

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=true, consistent with a read-only guide. Description adds that it returns markdown and covers specific syntax, which is useful context. No contradictions.

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

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

Two sentences, with the first clearly stating the purpose and content, and the second providing usage guidance. 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 simple guide tool with an output schema, the description fully explains what is returned and when to use it. No gaps.

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

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

No parameters exist. Schema coverage is 100% trivial. Description does not need to add param info, meeting the baseline for a parameterless 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 it returns the full spreadsheet authoring guide in markdown format, listing specific content areas. It also tells when to use it ('Read this FIRST when creating or editing a sheet'), effectively distinguishing it from sibling tools like 'edit_sheet' or 'create_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?

Explicitly says 'Read this FIRST when creating or editing a sheet', providing strong usage guidance. Does not explicitly mention alternatives or when not to use it, but the context of siblings (e.g., deck_authoring_guide) implies this is for sheets only.

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, destructiveHint=false, and the description adds useful context (scope of feedback). No contradictions, though it doesn't detail where feedback goes or any 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?

Two sentences, front-loaded with purpose and then an exclusion—no wasted words, highly 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?

For a simple feedback submission tool, the description is complete: it explains purpose, usage boundaries, and parameters are in the schema. Output schema exists, so return value explanation is not needed.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra meaning beyond the schema's parameter 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 'Submit free-text feedback about tela / tela-mcp itself'—a specific verb and resource—and distinguishes it from the sibling 'add_comment' by noting it is NOT for 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?

Explicitly states when to use (feedback about the tool itself) and when not to use (use add_comment for page content), with the alternative tool named.

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

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

Description adds semantic similarity mechanism and embedder requirement beyond annotations (readOnlyHint=true). No contradictions.

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

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

Two concise sentences that convey purpose, usage context, and prerequisite. Front-loaded and 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?

With output schema present, parameters fully described, and description covering use case and prerequisite, the tool description is complete for an AI agent.

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

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

Schema has 100% coverage, so baseline is 3. Description adds minor context for 'text' parameter but does not provide significant additional meaning beyond schema.

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

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

Clearly states it returns existing pages for linking given draft text, using semantic similarity. Distinguishes from siblings like search and related_pages by specifying authoring context.

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 says to use while authoring to wire a new page and avoid orphans. Mentions prerequisite (configured embedder). Does not explicitly state when not to use, but context is clear.

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

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

The description details the treatment process (crop, duotone, grain, scrim), the prerequisite (upload attachment), and the output (new attachment with snippet). Annotations already declare readOnlyHint=false, but the description adds behavior context like non-destructive saving and return format.

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?

Concse two paragraphs: first states purpose and process, second gives usage rules and reference. Every sentence adds value, no fluff.

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

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

Given 5 params, output schema exists, and description covers workflow, return format, and usage pitfalls. References additional module. Complete for an agent to use correctly.

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

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

Schema coverage is 100% with good descriptions, so baseline is 3. The description adds extra context: explains mode as 'duotone or none', scrim options, and variant fallback. It provides a higher-level understanding of parameter interactions.

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: 'Make an image tahta-grade for a deck's variant' with specific actions (crop, duotone, grain, scrim). It distinguishes from siblings like 'generate_deck_image' by explaining this is a fallback step.

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

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

Explicit guidance is provided: 'FALLBACK for off-palette or reused images; prefer rich on-palette images raw, and never duotone a real-colour focal subject — use mode=none.' Also references the imagery capability module for more 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?

The description adds valuable behavioral context beyond annotations: body changes auto-snapshot a revision, and it details the rich block palette and deck/sheet modes. However, it may contradict idempotentHint=true because auto-snapshots imply each call creates a new revision, which is not strictly idempotent.

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 core action and then provides extensive, well-structured guidance. While lengthy, each sentence adds value and covers essential use cases without redundancy.

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

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

For a tool with 4 parameters, nested objects, and an output schema, the description covers all parameters, explains behavioral side effects (auto-snapshot), and gives complete usage guidance for special modes. It fully equips an agent 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?

With 100% schema coverage, the baseline is 3. The description adds meaning beyond the schema by explaining that body supports a rich block palette, props replaces the whole bag with reserved keys ignored, and provides special case guidance for deck and sheet modes.

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 patches a page's title and/or body, with the specific verb 'patch' and the resource 'page'. It distinguishes itself from siblings like create_page, delete_page, and get_page by explicitly covering update scenarios.

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

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

The description provides explicit when-to-use guidance, including special cases for presentations (set deck=true) and spreadsheets (set sheet=true), and directs to alternative tools like deck_authoring_guide and sheet_authoring_guide. It also mentions resources like tela://authoring-guide.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false, so the description need not restate those. The description adds the permission note ('editor+') which provides useful context beyond annotations, but does not disclose additional behavioral traits such as side effects or rate limits.

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

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

The description is a single, front-loaded sentence with no wasted words. Every element earns its place: verb, resource, fields, permission.

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 patch tool with 3 parameters and an existing output schema, the description is mostly complete. It mentions the fields and permission. However, it could briefly note what the response looks like or any constraints (e.g., slug format). Without the output schema shown, this is a minor gap.

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

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

Schema coverage is 100% with clear descriptions for all parameters. The description adds no new meaning beyond the schema, which already explains 'omit to leave unchanged'. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Patch' and the resource 'space', specifying the fields 'name and/or slug' and the permission requirement 'editor+'. This distinguishes it clearly from sibling tools like create_space and delete_space.

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 updating space name/slug but does not explicitly state when to use or when not to use, nor does it mention alternatives. No guidance on prerequisites beyond 'editor+' permission.

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

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

Discloses inline base64 mechanism, 5 MB cap, return of serve URL and markdown snippet, and required follow-up. Annotations already signal mutability; description adds useful constraints.

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 action and resource, no wasted words. Structure clearly presents purpose, behavior, alternatives, and limitations.

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 schema richness, annotations, and output schema presence, description covers all needed context: when to use, limitations, return value format, and required subsequent step.

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?

Parameters fully described in schema (100% coverage). Description adds operational context like file name extension driving type detection and base64 encoding with URL prefix acceptance. Slightly above baseline.

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

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

Clearly states it uploads a file (base64) and attaches to a page. Specifies file types and return value. Distinguishes from siblings by mentioning alternatives for larger files.

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

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

Explicitly says to use for small files (screenshots, charts, short PDFs) and for larger files use request_attachment_upload or tela editor. Also notes need for subsequent call to update_page/patch_page.

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