tela

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

The description discloses that comments are root (non-reply) and anchored by a text triplet to stay pinned. It explains idempotency behavior: retries return original comment. Annotations are consistent (readOnlyHint=false, destructiveHint=false). 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 efficient sentences: first covers the action, anchoring, and idempotency; second provides usage guidance. Every sentence adds unique value with no redundancy.

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

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

Given the tool's complexity (nested anchor object, optional idempotency key, output schema exists), the description covers anchoring mechanics, idempotency, and usage context. Output is covered by output schema, so no 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%, so baseline is 3. The description adds value by explaining the anchor triplet purpose and idempotency key behavior, going beyond schema descriptions. It also notes the comment is a root comment.

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 attaches a root (non-reply) comment to a page with a specific anchoring mechanism. It explicitly distinguishes itself from the sibling tool 'submit_feedback', leaving no ambiguity about 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 explicit usage guidelines: use for feedback on page content, and redirects users to 'submit_feedback' for reporting problems with tela itself. It also explains when to use the idempotency_key for retries.

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, so the description adds value by detailing the scope (personal plus org projects) and the can_manage flag indicating permission to trigger runs. No contradictions. Slight deduction for not mentioning any rate limits or pagination (but output schema likely 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, no wasted words. First sentence states purpose and scope; second adds detail and use case. Perfectly front-loaded and efficient.

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

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

The description is complete for a simple list tool with zero parameters and an output schema. It covers what the tool returns, who can see what, and a key use case. 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?

Input schema has zero parameters and schema coverage is 100%, so the description has no burden to add parameter info. Baseline 4 for zero parameters 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 starts with 'List the atlas doc-generation projects you can see', which is a specific verb+resource+scope. It enumerates the fields returned (owner, output space, schedule, source count, latest-run summary, can_manage) and a clear use case (find project_id for atlas_run, read coverage health). This distinguishes it from siblings like atlas_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?

The description explicitly says 'Start here to find a project_id for atlas_run, or to read coverage health at a glance', providing clear when-to-use guidance. It doesn't explicitly state when not to use, but the context is sufficient given the sibling tools.

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

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

Discloses key behaviors: fetches sources, spends LLM budget, rewrites generated subtree, creates output space on first run, returns run_ids and 503 error. Adds value beyond annotations which only indicate non-destructive and non-read-only.

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

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

Concise, front-loaded with purpose, and every sentence adds value—no redundancy or fluff.

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

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

Given presence of output schema, description sufficiently covers return values (run_ids) and error conditions (503 ai_unavailable), along with permissions and side effects.

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

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

Schema covers project_id with description, and the description reinforces where to obtain it ('from atlas_list_projects'), aiding in parameter selection and reducing ambiguity.

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 triggers a full doc-generation run for all sources in an atlas project. Specific verb 'trigger', resource 'atlas project', and differentiates from sibling tools 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?

Explicitly states management-level access requirement (project owner/org admin), mentions spending LLM budget, and explains the 503 error condition. Lacks explicit when-not-to-use guidance but provides strong context for appropriate use.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the agent knows it is a safe read operation. The description adds behavioral context by detailing the return values (status, stage, coverage, stats) and their semantics, which goes 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 concise (about 50 words) and front-loaded with the purpose. Each sentence adds value: purpose, return details, and usage guidance. No redundant information.

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

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

The description fully explains the output including status, stage, coverage metrics (must_rate, surface_rate, gap_count, gap list), and stats (files, surface, chunks, pages). It also provides usage context. With an output schema present, the description covers all necessary details.

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

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

The input schema has only one parameter (run_id) with 100% description coverage, so the schema already explains it. The description mentions 'run_id (view+)', which might hint at required permissions, but does not add significant meaning beyond the schema. 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 reads an atlas run's status and coverage by run_id, specifying the verb ('read') and resource ('atlas run status'). It distinguishes from the sibling 'atlas_run' which starts the run, and details the output.

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

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

The description explicitly states when to use: 'Use to follow a run started by atlas_run to completion and judge whether the docs are complete.' This provides clear context and implies not to use it before starting a run, with 'atlas_run' as the complementary 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 indicate idempotentHint=true and destructiveHint=false, providing safety info. The description adds context about return value and workflow but doesn't elaborate on auth beyond 'Editor+' or potential 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 efficiently convey key information: action, output, prerequisite, permission, and next steps. No excess or redundancy.

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

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

For a single-parameter tool with output schema, the description covers workflow, permission, and integration hints. Minor gap: no mention of error if upload_id is invalid or PUT incomplete.

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 a clear description for upload_id linking it to request_attachment_upload. The description doesn't add further parameter details, so 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 tool returns the serve URL and markdown for a confirmed upload, distinguishing it from the sibling request_attachment_upload which initiates the upload.

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

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

Explicitly states the prerequisite of using request_attachment_upload and PUTting bytes before calling this tool, and advises subsequent use of update_page/patch_page. However, it does not contrast with alternatives like upload_attachment.

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

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

Annotations already indicate a write operation (readOnlyHint=false) with no destruction (destructiveHint=false). The description adds significant behavioral context: backlinks are indexed for tela:// links and wikilinks, tela renders a rich block palette beyond plain markdown, and special content types (decks, sheets) require different body format and properties. This goes well beyond what annotations provide.

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

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

The description is well-structured and front-loaded with the core purpose, then details. It is somewhat lengthy due to rich block palette enumeration and special case instructions, but every sentence earns its place. Minor conciseness improvements could be made, but overall effective.

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

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

Given the tool's complexity (6 parameters, special content types, backlink indexing) and existence of an output schema, the description is thorough. It explains the body format, links, rich blocks, deck/sheet conventions, and directs to additional guides. No gaps are apparent for the agent to misuse 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%, baseline 3. The description adds substantial meaning: body is markdown with special link types, and for decks/sheets the body format and props must be set differently; props have reserved keys; idempotency_key enables safe retries. These details greatly enhance understanding beyond the schema descriptions.

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

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

The description explicitly states 'Create a page in a space (editor+).' It clearly distinguishes from sibling tools like update_page, patch_page, delete_page, and from deck/sheet authoring guides. The verb 'create' with resource 'page' is 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?

The description provides explicit guidance: when to use this tool (to create a page), and when not (for presentations/decks or spreadsheets, directing to deck_authoring_guide and sheet_authoring_guide). It also instructs to prefer rich blocks and read the authoring guide for syntax. This is exemplary usage differentiation.

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 readOnly=false and destructiveHint=false, indicating a write operation that is not destructive. The description adds the caller becoming owner, which is beyond annotations. However, it does not mention any other side effects or authorization requirements, so it is not fully exhaustive.

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 unnecessary words. Every sentence adds value: purpose, ownership, slug behavior, and usage compared to siblings.

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 does not need to explain return values. It covers creation behavior, ownership, and clearly distinguishes from related tools. Given the tool's complexity and schema richness, the description is 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% with detailed parameter descriptions. The description adds context about slug derivation ('slug is derived from name when omitted'), which reinforces the schema but provides minimal extra value. 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 'Create a space' with a specific verb and resource. It distinguishes itself from siblings by mentioning create_page (adds page inside existing space) and update_space (renames), ensuring no confusion with other space-related 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?

Explicitly provides usage context: 'Use to start a new top-level container of pages' and lists alternatives (create_page for adding pages, update_space for renaming). This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint and destructiveHint. Description adds that it returns markdown, lists content types, and describes module usage, providing 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?

Three concise sentences with no fluff. Front-loaded with core purpose, followed by usage guidance and module explanation.

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

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

Given the simple tool (one optional parameter, annotations, output schema), the description covers purpose, usage, and parameter behavior fully. 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 coverage is 100%. Description reinforces the parameter's purpose and adds usage context ('when one applies, call again with module="<id>"'), enhancing meaning beyond the schema alone.

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

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

Description states 'Return the full tela deck authoring guide as markdown' specifying the resource and action, and distinguishes from siblings by advising 'Read this FIRST' when creating or editing a deck.

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 read this first when creating or editing a deck, avoiding guesswork. Also explains how to use the module parameter for extra guidance. 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?

Annotations already indicate destructiveHint=true. The description adds the key behavioral detail that it is a soft-delete, and confirms no impact on page body, providing 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 concise sentences. First sentence covers main purpose and prerequisites; second clarifies limitations and alternatives. No fluff, 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 simple deletion tool with 2 parameters and output schema, the description covers purpose, usage, behavioral traits, and schema references adequately. No gaps given the complexity.

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

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

Schema covers 100% of parameters with descriptions. The tool description does not add extra parameter details beyond what is already in the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states 'Detach a file from a page by attachment id', specifying the action, resource, and identifier. It also distinguishes from editing the page body, differentiating it from sibling tools like update_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 states when to use ('editor+; ids come from list_attachments') and when not to use ('It does NOT edit the page body'), with clear alternatives ('remove any inline embed separately with 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.

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

Annotations already declare destructiveHint=true. The description adds valuable behavioral context: backlinks are preserved with the last-known title. This goes beyond what annotations provide, though it omits details like deletion permanence or side effects on other entities.

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: two sentences, no filler. The action is front-loaded in the first sentence, and the second sentence provides a key behavioral note. 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 the tool's simplicity (1 parameter, output schema exists), the description covers the core action and an important side effect (backlink preservation). It does not address potential error states or data consequences, but it is reasonably complete for the complexity level.

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

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

Schema coverage is 100%, and the parameter `id` is clearly documented in the schema as 'page id to delete'. The description does not add any additional parameter semantics, so it meets the baseline expectation.

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 'Delete a page (editor+)', with a specific verb and resource. It distinguishes from sibling tools like create_page, update_page, and delete_space by specifying the target (page) and required permission level.

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 indicates use for deleting pages with editor+ permissions. It does not explicitly state when not to use or provide alternatives, but the context of sibling tools and the clear action makes the usage fairly obvious.

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 confirm destructiveHint=true, but the description adds important context: cascading deletion of all associated content, ownership requirement, and irreversibility. These details enhance agent understanding 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 extremely concise (two sentences) and front-loaded with the core action. Every word adds value—'Delete a space AND all its pages, comments, revisions and share links. Owner only. Irreversible.'

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 presence of an output schema, the description does not need to detail return values. It adequately covers scope, prerequisites, and irreversibility. The context of sibling tools (e.g., delete_page, update_space) is addressed indirectly by specifying the full cascade.

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

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

Schema description coverage is 100% for the single parameter, with 'space id to delete (cascades)' in the schema. The tool description does not add additional meaning to the parameter beyond what the schema provides, so 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 action ('delete'), the resource ('space'), and the cascading effect on pages, comments, revisions, and share links. It distinguishes itself from sibling tools like delete_page or delete_attachment by specifying the full scope.

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

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

It explicitly states 'Owner only' and 'Irreversible', providing clear guidance on when to use (only if owner) and the consequence. It does not mention alternatives like archiving, but for a destructive operation this 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 only state non-read-only. The description adds critical behavioral details: operations are atomic, errors are fixable, returns updated sheet with computed formulas, and warns against manual editing to avoid grid corruption. This far exceeds the annotation burden.

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 dense but well-structured, starting with purpose and preference. Every sentence adds value, though it is slightly verbose for a single tool. Could be tightened by removing redundant 'Pass one op (or a batch...)', but overall efficient.

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

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

Given the tool's complexity (multiple op kinds, batch, atomicity, output schema), the description is remarkably complete. It covers all key aspects: permission, behavior, error handling, output, and points to additional reference. No significant gaps remain.

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

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

Schema coverage is 100%, yet description adds substantial meaning: explains 'op' structure with examples per kind, 'ops' batch with atomicity, and clarifies 'page_id'. Provides context that schema alone cannot, like 'A1 ref' and optional 'sheet' per op.

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 'edit' and resource 'sheet', differentiates from 'update_page' by explicitly preferring this tool for sheets, and specifies 'STRUCTURED edit' with 'editor+' permission. It leaves no ambiguity about what the tool does and its unique value.

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 'Prefer this over update_page for sheets', implying when to use (sheets) and when not (non-sheet pages). It also directs to 'sheet_authoring_guide' for full details, providing clear guidance on alternatives and additional resources.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that the tool is read-only and returns 'full text', which aligns with annotations. It does not contradict, but could mention more about the response shape or limitations.

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

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

The description is concise (two sentences), front-loaded with purpose, and includes essential usage guidance without unnecessary words. Every sentence adds value.

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

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

Given the tool's simplicity (one required parameter, output schema exists), the description covers purpose, alternative use cases, and context. It is complete for the agent to decide when to invoke.

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 parameter 'id' is already well-described in the schema as 'page id, as returned by search results'. The description adds no further semantic details, so 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 a specific verb ('Fetch') and resource ('tela page's full text by id'), and distinguishes itself from sibling tool 'get_page' by noting it is a 'fixed-shape' companion to 'search'. It clearly states what the tool does and how it differs.

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: 'Prefer get_page for normal use... reach for fetch only when the Deep Research search/fetch contract requires it.' It also specifies that the id comes from a search result, setting clear context for use.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false. Description adds transparency by specifying return of page pairs and chunk-level similarity mechanism, without contradicting annotations.

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

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

Single sentence front-loads the verb and resource, with no extraneous words. Every part adds value.

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

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

Output schema exists, so return values are covered. Description addresses purpose, optional parameters, and defaults, sufficient for a read-only list tool with clear 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%, but description adds meaning by explaining 'limit' as max pairs, 'space_id' as optional restriction, and 'threshold' as minimum cosine similarity with default 0.92, enhancing schema descriptions.

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

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

The description clearly states it finds near-duplicate page pairs that share a near-identical passage, with a specific wiki hygiene goal. It distinguishes from siblings like 'related_pages' by focusing on merge/redirect candidates.

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?

Describes optional parameters for restricting to a space and setting threshold, implying usage for duplicate detection. Does not explicitly state when not to use, but the context of wiki hygiene and 'near-duplicate' pairs provides implicit 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?

Beyond annotations (readOnlyHint=false, etc.), the description adds critical behaviors: attaches to deck page, requires editor+, returns URL and snippet, may be unavailable (503), generation time varies, and advises against regeneration. Model-specific advice (FLUX) further enhances transparency.

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

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

Front-loaded with main action and returns. While somewhat lengthy, every sentence adds value. Could be slightly trimmed but remains efficient for the information density.

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

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

Covers all necessary aspects: action, requirements, usage rules, error conditions, timing, and return format. With an output schema existing, the description still provides ample context for correct invocation.

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

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

Schema coverage is 100%, but description adds meaningful guidance: rich prompts with FLUX append note, steps number suggestions, size default with aspect ratio. This elevates understanding beyond schema definitions.

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 specifies the verb 'generate' and the resource 'image from a prompt attached to a deck page'. It distinguishes from siblings like 'treat_deck_image' by focusing on generation with prompt, and provides context on usage (atmosphere/concept/focal only).

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

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

It explicitly states when to use ('atmosphere/concept/focal only'), when not to use ('most slides need NO image'), and directs to the imagery module for guidance. Also mentions potential unavailability and timing, aiding agent decision.

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 the epistemic block with detailed fields (freshness, provenance, corroboration) and their implications. Exceeds what annotations provide (readOnlyHint, no destructive/ openWorld). 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?

Concise, front-loaded with purpose, and each 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 output schema exists, description covers all necessary context: what is returned, parameter modes, and how to use the epistemic block. Adequately handles tool complexity.

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

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

Schema coverage is 100%, but description adds significant value by explaining each format option: 'full' returns markdown body, 'map' returns heading outline (cheap, targets for patch_page), 'values' returns computed spreadsheet for sheet pages. This clarifies usage 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 'Full markdown body + metadata for a numeric page id', specifying the resource and verb. It distinguishes from siblings by focusing on retrieval of content and trust signals, not modification or listing.

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 how to interpret the epistemic block ('prefer fresh, corroborated, human-reviewed pages'), which helps in acting on the output. Implicitly indicates when to use the tool (when full content and trust signals are needed) vs alternatives like format='map' for cheap outlines.

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, so the 'Read-only' tag is redundant but helpful. The description adds value by specifying the exact returned fields (id, name, slug) 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 dense sentences with no wasted words. Purpose is front-loaded, and usage guidance is concise. Perfect for quick agent comprehension.

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 a simple tool with one parameter, an output schema (not shown), and clear annotations, the description covers purpose, usage, and alternatives completely. 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 coverage is 100% with a clear description of 'id' as 'space id'. The description does not add extra semantic meaning beyond the schema, so 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 'fetch', the resource 'one space's metadata', and the specific fields ('id, name, slug'). It distinguishes itself from siblings by saying 'use when you already hold a space_id and just need its name/slug', contrasting with list_spaces and list_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?

Explicitly states when to use ('when you already hold a space_id and just need its name/slug') and when not to (for discovery or listing pages), with direct alternatives: list_spaces and list_pages.

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

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

Annotations already declare readOnlyHint and destructiveHint. The description adds that it exposes users' questions and is admin-only, which are behavioral traits beyond annotations (privacy/access).

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 purpose, second adds access constraint and optional parameter. No wasted words, 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?

Tool has an output schema, no required params, simple behavior. Description fully covers what the tool does, its access restrictions, and the optional time window. Complete for this use case.

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 detailed descriptions for both parameters (limit and since_days). The description only mentions 'Optional since_days window' which doesn't add new meaning beyond the schema. Baseline 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?

Description clearly states it returns 'the most-asked ask your docs questions the corpus could NOT answer — a content roadmap.' This is a specific verb+resource, and the purpose is distinct from sibling tools like list_pages or search.

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

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

The description notes 'Instance-admin only (exposes users' questions)' and 'Optional since_days window,' providing clear context and parameter guidance. No explicit alternatives or when-not-to-use, but adequate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so description adds value by stating it returns structured issues per slide, which provides context beyond the safety profile. 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, each with clear purpose. First sentence defines action, second gives usage timing and output, third references sibling. 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?

Complete for a simple tool: explains what it does, when to use, what output to expect (structured issues), and where to find more info (deck_authoring_guide). Output schema presumably covers return format.

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

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

Schema coverage is 100% with clear description for the single parameter 'id'. Description does not add extra meaning beyond the schema, so 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?

Description clearly states verb 'Validate', resource 'deck page's slides', and scope 'against the tahta theme contract' including specific checks (unknown layouts, missing required fields, type/format mistakes). Distinguishes from siblings like deck_authoring_guide.

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.' Also provides exclusion and alternative: 'For the full list of valid layouts ... call deck_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 declare readOnlyHint=true and destructiveHint=false. Description adds key behavioral details: lists both upload and rclone-synced files, provides specific fields including 'embedded' flag indicating if file is referenced in page body.

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

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

Two concise sentences front-load the purpose, with no redundant or extraneous 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 output schema present, description still lists return fields. Single required parameter, annotations present, and description covers purpose and behavioral context fully.

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%; description does not add extra meaning beyond the schema's 'page whose attachments to list'.

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 specifies verb 'List', resource 'attachments of a page', and lists returned fields (name, mime, size, URLs, markdown snippet). Distinguishes between upload and rclone-synced 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?

Implies usage for listing page attachments, but no explicit guidance on when to use vs alternatives (e.g., upload_attachment) or when not to use.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's safe. Description adds that it lists only [[wikilink]] and tela:// page links, which is useful 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?

Two sentences, front-loaded with purpose, second sentence adds 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 tool with one parameter, annotations, and output schema, the description is complete. It covers purpose, usage context, and an alternative, fulfilling the agent's needs.

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 a clear description for page_id. The description restates the parameter meaning but does not add significant new semantics beyond the schema.

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

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

The description clearly states it lists incoming references (backlinks) to a page via explicit wikilinks or tela:// URLs. It uses a specific verb 'list' and resource 'backlinks' and distinguishes from sibling '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?

Explicitly tells when to use: before editing/deleting a page to see dependencies or to walk the link graph. Also provides an alternative: for semantically similar pages not linking, use related_pages.

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 readOnly=true; the description adds that the listing is 'flat' and per-space, but does not mention pagination or ordering. This is adequate but could be more specific.

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 efficiently convey the core purpose, safety, and alternative tools. Front-loaded with the main action and read-only nature.

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 presence of an output schema, the description sufficiently covers the tool's usage scenarios, relationships with siblings, and parameter guidance for a simple listing 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%, but the description adds the crucial detail that parent_id returns 'direct children' rather than all descendants, which is not explicit 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 the tool's purpose: listing pages in a space, and distinguishes it from sibling tools by specifying that 'search' is for keyword search and 'get_page' is for reading page body.

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 explains when to use the parent_id parameter and when to omit it, and provides guidance on using alternative tools for different needs (search for keywords, get_page for body).

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 important context beyond annotations: active-only default, revoked links optional, and requires write-scoped key due to bearer secrets. Discloses returned fields.

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

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

Two sentences, front-loaded purpose, no waste. Efficient 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?

Output schema exists and annotations present. Description covers purpose, parameters, and key security requirement; complete for a listing 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 100%, but description adds meaning to include_revoked (default behavior) and clarifies page_id context (page's share links).

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 verb 'List' and resource 'page's public share links' with scope (editor+). No explicit sibling differentiation, but the purpose is distinct from share_page and revoke_share.

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 parameter usage (include_revoked), but no explicit when-to-use vs alternatives or when-not-to-use.

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

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

Annotations already declare readOnlyHint=true, so the description adds value by specifying the returned fields (id, name, slug) and confirming read-only nature. No additional behavioral traits are needed.

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. Every sentence adds value without waste.

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

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

With 0 parameters and an output schema present, the description fully explains what the tool does, what it returns (fields), 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?

There are 0 parameters, and schema coverage is 100%. The description does not need to add parameter info. Baseline 4 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 'List every space the API key can access' with specific verb and resource. It distinguishes from siblings by noting 'for a single space you already know, use get_space instead'.

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 start here to discover a space_id for other tools when you don't have one, and advises using get_space for a known single space. This provides clear when-to-use and when-not-to-use guidance.

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

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

Adds behavioral context beyond annotations: permission requirements and parameter mutual exclusivity (make_root vs parent_id). Annotations already indicate idempotent and non-destructive, and the description does not contradict.

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

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

Three sentences, each serving a distinct purpose: operations, permissions, constraints. No redundant or extraneous text.

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

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

With output schema present, the description covers all necessary aspects: actions, constraints, and permissions. No critical gaps for an idempotent, non-destructive move 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%, and the description adds value by grouping parameters by operation and clarifying constraint ('mutually exclusive with parent_id'). This reduces ambiguity about which parameters to combine.

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 (move a page) and specifies the four operations (reparent, detach, reorder, relocate). It distinguishes this tool from sibling tools like update_page and patch_page by focusing on structural movement rather than property updates.

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 permission requirements ('Editor+ in both source and target space') and mandatory parameter condition ('Provide at least one of...'). No explicit comparison with alternatives, but the constraints are sufficiently clear for correct usage.

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

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

The description goes beyond annotations by stating 'never touches the rest of the document' and 'snapshots a revision like any edit.' Since annotations declare readOnlyHint=false and destructiveHint=false, the description adds valuable context about safety and revision behavior 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 sentences that are dense with information: first sentence states purpose and comparison, second provides workflow step and safety reassurance. No unnecessary words, front-loaded with key action.

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

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

Given the presence of an output schema, the description covers all needed context: when to use, prerequisites, behavioral traits, and parameter details. It is fully adequate for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description adds meaning: it explains how 'target' works (heading path from get_page map), describes operations (append, prepend, replace, delete), and clarifies content usage ('markdown to insert; omit for delete'). This enriches parameter understanding.

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: 'Surgically edit ONE section of a page instead of rewriting the whole body.' The verb 'surgically edit' and resource 'page section' are specific, and it distinguishes from sibling tool 'update_page' by emphasizing that it only edits one section.

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: 'First call get_page format:"map" to see the section paths,' and it compares to update_page: 'cheaper and safer than update_page on a long page — it never touches the rest of the document.' This tells the agent when and how to use the tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds valuable behavioral context: 'Renders are cached', which is not in annotations. No contradictions.

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

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

Three sentences: purpose, parameter usage, and caching behavior. Every sentence adds value and is front-loaded. No unnecessary words.

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

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

Given the tool's simplicity (2 params, no output schema), the description covers purpose, parameter usage, and caching. It could be improved by describing the return format (e.g., list of image URLs), but is mostly 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 both parameters have clear descriptions in the schema. The description repeats the slides parameter guidance but adds no new meaning beyond the schema. 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's purpose: 'Render a deck page to slide images and return them'. It distinguishes from sibling tools like 'generate_deck_image' by emphasizing visual preview ('so you can SEE how the deck looks') and advising not to author blind.

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

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

The description provides clear context: use to see how the deck looks before authoring. It gives parameter guidance ('Pass slides to preview specific 1-based frames; omit for the first few') but does not explicitly mention 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 and destructiveHint. Description adds context about returning section text and file chunk details (file_name, parent page_id, download_url), which is valuable 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 main action, 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 output schema exists, description adequately covers what the tool does, granularity, and special behavior for file chunks.

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 a clear description of chunk_id. Description adds context that the ID comes from a research result, but doesn't add formatting or constraints 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 it fetches one chunk's full section text by chunk_id from a research source, specifying page or file chunk (read-only). It distinguishes from get_page for whole 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 'Middle granularity — use it to expand a single cited section; for the whole page use get_page.' Also describes file chunk citations.

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 tool is read-only and uses stored vectors (no live embedder), providing extra behavioral context beyond annotations. No contradictions.

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

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

Two sentences, front-loaded with the main purpose and nature, followed by usage guidance. Every sentence adds value with no unnecessary words.

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

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

Covers purpose, usage guidelines, behavioral traits (read-only, stored vectors), and distinguishes from sibling. Given the presence of output schema (handles return details), the description is sufficiently complete.

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

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

Both parameters (page_id, limit) have full descriptions in the input schema (100% coverage). The description does not add additional detail beyond what the schema provides, so 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 that the tool returns pages semantically related to a given page, ranked by similarity, and distinguishes it from list_backlinks which returns explicit links. It uses specific verbs and resources ('pages semantically related', 'discovery beyond explicit links').

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 ('Use for topically similar pages') and when not to use ('for pages that explicitly link this one, use list_backlinks'), providing a specific alternative. Also mentions it works without a live embedder, giving additional 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 significant behavioral context beyond annotations: it explains the purpose of the signed URL (direct upload), the required outbound HTTP PUT capability, and the follow-up actions (reading response or calling confirm_attachment_upload). 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 concise, with each sentence serving a purpose: purpose, flow, conditions, and alternatives. It is front-loaded with the key action and provides structured guidance 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 presence of an output schema (not shown but indicated) and the tool's complexity (multi-step flow), the description covers all necessary context: usage conditions, step-by-step flow, prerequisites, and alternatives. It is complete and actionable 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 coverage is 100%, so baseline is 3. The description adds value by explaining that 'mime' is an optional content-type hint and that the server trusts magic bytes for images, and that 'name' should include the extension. This nuance improves parameter understanding.

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 gets a short-lived signed PUT URL for uploading files, distinguishing it from upload_attachment by avoiding context bloat and handling large files. It specifies the resource (PUT URL) and verb (request/get), making the purpose unambiguous.

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

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

The description explicitly states when to use this tool (files over 5 MB or to avoid context bloat) and when not to (if host cannot make outbound HTTP PUT, then use upload_attachment). It also provides a clear flow of steps to follow after obtaining the URL.

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 valuable behavioral context beyond annotations: it returns context, sources, disagreements, and low_confidence signals; it pulls from pages and attached files; it assembles answer-ready grounding in one call. No contradictions.

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

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

The description is well-structured and front-loaded with purpose, followed by return values and alternatives. It is efficient but slightly longer than necessary; however, every sentence adds value.

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

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

Given the tool's complexity (3 parameters, output schema, many siblings), the description is complete. It explains return types, prerequisites, and error conditions, and references alternatives. The output schema exists, so full return structure details are 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 coverage is 100% with all parameters described. The baseline is 3. The tool description does not add additional parameter-level detail beyond what the schema already provides, so the score remains at 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 clearly states the tool's purpose: 'Answer a question — or gather everything relevant on a topic — from the wiki by MEANING.' It uses a specific verb+resource combination and explicitly distinguishes from sibling tools like search (exact-name/term lookup), read_chunk, and get_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 provides explicit guidance on when to use alternatives: 'To read one section deeper use read_chunk ... or get_page. For exact-name/term lookup use search.' It also notes a prerequisite (requires configured embedder) and mentions the error code 503 if 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 indicate destructive and idempotent behavior. Description adds valuable context: immediate effect ('stops working immediately') and confirms idempotency as a no-op. 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, no wasted words. Front-loaded with the action, followed by key details and idempotency note. Excellent structure.

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

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

For a simple tool with one required parameter and an output schema, the description covers all essential aspects: purpose, effect, safety (idempotent), and parameter source. No gaps.

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

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

Only one parameter with 100% schema coverage. Description adds meaning by specifying source of share_id (from list_shares) and access level (editor+), going beyond the schema definition.

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

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

Clearly states the action (disable/revoke), resource (public share link), identification method (by share id from list_shares), and immediate effect. Distinguishes itself from sibling tools like list_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?

Provides context on when to use (to revoke a share link) and mentions prerequisite (ids from list_shares). Does not explicitly state when not to use or alternatives, but the intent 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?

Adds value beyond annotations by noting it works without an embedder (always available) and that space_id narrows results. No contradiction with annotations.

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

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

Two sentences: first defines core functionality, second gives usage guidance and alternative. Very concise and front-loaded.

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

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

Given simple schema, output schema exists, and annotations cover safety, the description fully addresses purpose, usage, and behavioral context.

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

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

Schema coverage is 100% so description adds little beyond confirming defaults and indicating space_id is optional. Baseline 3 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?

Description clearly states keyword full-text search over title+body with ranking and snippet highlighting, distinguishing it from siblings by noting it works without an embedder and contrasting with 'research' for semantic queries.

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 ('find a page you can name or that contains an exact term') and when not to ('use research instead for meaning'), providing 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?

Beyond annotations, it discloses that each call mints a new link, explaining idempotency. It also describes return values and options. 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?

Concise paragraph with no fluff. Front-loaded with purpose, then options, then behavior, then comparisons. Each sentence is essential.

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

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

Covers purpose, parameters, return values, behavior, and relations to other tools. Complete for a mutation 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%, but description adds context: include_descendants shares subtree, password gates behind passphrase, expires_at format and behavior. Adds 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?

The description clearly states 'Mint a public share link for a page' with specific verb and resource. It distinguishes from sibling tools like list_shares and revoke_share.

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 this tool (sharing a page tree) and when not to (for a whole space, use space visibility setting). Mentions alternatives like list_shares and revoke_share.

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 the description adds value by specifying the returned content (markdown guide). It does not contradict annotations and provides sufficient 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?

Two sentences: first states what it returns, second states when to use it. No fluff, front-loaded with key 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 (no parameters, output schema exists), the description is fully complete. It explains what, when, and why, with 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 (0 params, schema coverage 100%). The description correctly adds no parameter info, as none are needed. Baseline 4 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 it returns the full sheet authoring guide as markdown, listing specific content (Defter text format, coordinates, formulas, syntax). It also gives a usage instruction: read this first when creating/editing a sheet. This distinguishes it from action-oriented siblings like edit_sheet.

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' and advises against guessing. This tells the agent exactly when to use this tool and provides context for sequence of operations.

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

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

Annotations already indicate this is a mutation (readOnlyHint=false) but not destructive. The description adds the scope constraint but does not disclose additional behaviors such as confirmation, rate limits, or side effects beyond the basic submission action.

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, zero waste. The purpose and exclusions are front-loaded, making it easy for an agent to quickly understand 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?

Given the presence of an output schema and full parameter descriptions, the description covers the essential context: what to submit and what not, with no missing information for correct agent invocation.

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

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

Schema coverage is 100%, so the description does not need to detail parameters. It does not add any extra semantics beyond what the schema already provides for subject, body, and kind.

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 submits free-text feedback about the tool itself, distinguishing it from page content feedback. It explicitly names a sibling tool (add_comment) for the alternative use case.

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

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

Provides explicit guidance on when to use (feedback about tela/tela-mcp) and when not to use (page content), with a direct reference to add_comment as the appropriate alternative.

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 description does not need to reiterate safety. It adds value by stating the embedder dependency and the semantic similarity approach, but does not disclose performance characteristics or rate limits. With annotations covering the core behavioral profile, a score of 3 is appropriate.

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

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

The description is two sentences long, efficiently front-loading purpose and usage. Every sentence adds value: first defines what and how, second gives when and a prerequisite. No redundant text.

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

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

Given an output schema exists (not shown but mentioned in context signals), the description does not need to detail return format. Parameters are fully documented in the schema, and the description covers usage context and dependencies. The tool is simple and well-defined, leaving no obvious gaps.

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

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

Schema coverage is 100% with clear descriptions for all three parameters. The description adds minimal additional meaning beyond calling the input 'draft text' and the output 'existing pages'. Since the schema already does the heavy lifting, no extra credit is warranted.

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: given draft text, return existing pages to link to via semantic similarity. It distinguishes itself from search or list tools by specifying 'semantic similarity' and authoring context. The verb 'suggest' and resource 'links' 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?

The description advises using the tool while authoring to avoid orphan pages, which gives clear usage context. It also notes the prerequisite of a configured embedder. However, it does not explicitly contrast with sibling tools like 'search' or 'related_pages', which could offer comparable functionality.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false. The description adds critical context: it modifies the image and saves a new attachment, returns a snippet, and warns against duotone on real-colour subjects. This goes beyond annotations, but annotations already establish mutability.

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 a single dense paragraph, efficient but packed with information. Could be slightly more structured (e.g., bullet points), but it front-loads the main action and follows with guidelines. 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 (5 params, prerequisite step, output snippet), the description covers all essential aspects: prerequisites, process, output format, and reference to the imagery module. The presence of an output schema reduces the need to detail return values.

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

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

Schema covers 100% of parameters. Description clarifies relationships (e.g., variant defaults to deck's own) and adds context for mode, scrim, and the required upload step. It enhances the schema without repeating it verbatim.

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 transforms an image into 'tahta-grade' by cropping to 16:9, applying duotone, grain, and optional scrim. It distinguishes itself from siblings like generate_deck_image and upload_attachment by its specific role as a fallback treat 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?

Explicitly states when to use: 'FALLBACK for off-palette or reused images' and when not: 'prefer rich on-palette images raw'. Provides prerequisite: upload with upload_attachment first. Names alternatives: use mode=none for real-colour subjects.

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 idempotent and non-destructive behavior. The description adds valuable context: body changes trigger automatic revision snapshots, reserved keys are ignored, and the rich block palette availability. This goes beyond annotations to inform the agent of side effects and capabilities.

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

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

The description is well-structured with a clear opening sentence, but it becomes verbose with extensive lists of block types and detailed instructions for decks and sheets. Some of this detail could be delegated to the referenced authoring guides, making the description more concise.

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

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

Given the tool's complexity and the presence of an output schema (not shown but noted), the description covers key aspects: authentication (editor+), side effects (snapshots), content capabilities, and special use cases. Minor gaps exist, such as error handling or rate limits, but overall it provides sufficient context 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 coverage is 100%, so baseline is 3. The description adds significant value by explaining the 'body' parameter's special formatting options (tela blocks, decks, sheets) and the 'props' parameter's reserved key behavior. This enriches understanding beyond the schema's basic 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 patches a page's title and/or body, with specific verb ('Patch') and resource ('page'). It distinguishes from creating a new page (different scope) and includes editor requirement, making purpose unambiguous. The context of slide decks and spreadsheets further clarifies use cases.

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

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

The description provides clear guidance on when to use this tool vs creating content types (slide decks, spreadsheets) with explicit instructions to set appropriate page properties. However, it does not directly compare to sibling tools like 'create_page' or 'patch_page' (if different), leaving some ambiguity about when to use 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?

Describes idempotency and permission level (editor+), and clarifies that slug change does not break existing links. All behavioral traits beyond annotations are covered.

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, no unnecessary words. Front-loads key action and idempotency.

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

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

Given the tool's complexity (3 params, no enums, output schema present), description covers all necessary aspects: action, parameters, side effects, alternatives.

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. Description merely rephrases the schema's info about omitting fields; adds marginal 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?

Clearly states it patches a space's name and/or slug, with correct verb and resource. Explicitly distinguishes from sibling tools (create_space, get_space, 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?

Explicitly tells when to use each sibling tool (create, read, delete) and explains behavior of slug change (URL updates, links resolve).

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses that the payload is inline base64 and rides through context, capping at 5 MB. Also states the return values (serve URL and markdown snippet) and how attachments render (images inline, other files as download card). 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?

Four sentences with no redundancy. The first sentence captures the core action and return, the second explains the workflow, the third gives the size constraint, and the fourth provides alternatives. Front-loaded and efficient.

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

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

The tool has an output schema, so return values are documented. The description covers the input, size limitation, integration step (update_page), and alternatives. For a file upload tool with moderate complexity, 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?

Schema coverage is 100% for all three parameters. The description adds value by explaining that 'name' drives the displayed name and type detection, and that 'data_base64' accepts a data URL prefix. It also ties the 5 MB limit to the payload parameter, which is critical for agent decision-making.

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: 'Upload a file (base64) and attach it to a page'. It specifies the supported file types (image, PDF, dataset) and distinguishes from siblings like request_attachment_upload for larger files. The verb 'upload' combined with the resource 'attachment' and page context leaves no ambiguity.

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 on when to use this tool (small files up to 5 MB) and when to use alternatives (larger files use request_attachment_upload or editor drag-drop). Also explains the follow-up step: call update_page or patch_page to place the attachment in the body. No confusion about prerequisites or context.

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