tela

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

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, and the description adds context those hints cannot convey: the editor+ permission requirement, the root-vs-reply precondition on anchor, the rejection of replies-to-replies, and idempotency_key semantics for safe retries (a repeat returns the original comment rather than duplicating). No contradictions with 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?

Dense but front-loaded: the root-vs-reply rule leads, then anchor mechanics, then idempotency, then the sibling routing. Every sentence carries operational information, though the parenthetical-heavy run-on style makes it a wall of text rather than cleanly chunked guidance.

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 5-parameter mutation tool with an output schema (so return values need no explanation) and annotations covering the safety profile, the description covers the remaining gaps: permissions, the anchor precondition for roots, the reply precondition and its rejection case, and retry safety. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not carry: anchor text must be the page's plain text with markdown markers stripped (`**ship it**` -> `ship it`), blocks joined by single newlines, and prefix/suffix limited to at most 32 characters of context. It also explains the retry behavior of idempotency_key beyond the schema's brief note.

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

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

States a specific verb+resource ('Comment on a page') and immediately scopes it with a permission level ('editor+'). It distinguishes itself from siblings by explicitly routing 'problems with tela itself' to submit_feedback and by separating root comments from replies, so an agent can tell it apart from list_comments and update_comment.

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

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

Gives explicit branching rules: omit parent_id for a root comment (which then requires an anchor), pass parent_id to reply inside a thread, and use submit_feedback for product problems. It also names a rejected case ('replying to a reply is rejected'), which is exactly the kind of exclusion that prevents misinvocation.

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 a safe read-only, closed-world operation, so the bar is lower. The description still adds useful context: the visibility rule (personal + all orgs) and the meaning of `can_manage` (whether you may trigger runs), which goes beyond what the safety hints 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?

Three sentences, front-loaded with the scope, then the payload contents, then the routing guidance. No sentence is filler; each adds a distinct fact.

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?

An output schema exists, so return fields need not be exhaustively explained, and for a zero-param read-only list the description covers scope, contents, and workflow entry point adequately. Nothing needed to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4 and there are no parameter semantics to document or compensate for.

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

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

States a specific verb (list) and resource (atlas doc-generation projects) plus the exact visibility scope (personal plus every org the user belongs to). An agent can distinguish it from siblings like atlas_run and atlas_run_status without opening any schema.

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 the agent to 'start here to find a project_id for atlas_run, or to read coverage health at a glance', naming the downstream tool and the reason to call this one. It does not state when-not to use it or contrast with atlas_run_status, so not quite a full 5.

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

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

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 cover the safety profile (write, non-destructive, idempotent, closed-world) and the description is consistent with them. It adds value beyond the annotations by disclosing what the call returns (serve URL + ready-to-embed markdown) and the 'Editor+' authorization requirement.

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?

Dense and front-loaded: the precondition comes first, then the return value, then the follow-up action. It is terse and every clause carries meaning, though the parenthetical and trailing instruction make it slightly crammed into one sentence.

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?

An output schema exists, so return values need not be fully explained, yet the description still summarizes them usefully. Combined with the permission note and the workflow chain (request_attachment_upload -> confirm -> update_page/patch_page), an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and the single parameter (upload_id) is fully documented in the schema as coming from request_attachment_upload. The description adds no format or syntax details beyond that, so baseline 3 applies.

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

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

States a specific verb (confirm) and resource (attachment upload), and pins the exact precondition: bytes already PUT to a request_attachment_upload URL. It clearly distinguishes itself from the sibling request_attachment_upload by describing the post-upload step rather than the request itself.

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 it (after the PUT to the request_attachment_upload URL) and names the follow-up tools (update_page/patch_page) for placing the snippet. The alternative path is also implied for hosts that can't read the PUT response, giving a clear routing 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?

Adds substantial behavior beyond the annotations: 'editor+' permission requirement, backlink indexing from tela://page links and [[wikilinks]], and the critical caveat that the reader silently drops raw HTML and unwraps unrecognized blocks in ways invisible from the markdown. That silent-mutation disclosure is exactly the kind of context annotations (readOnly=false, destructive=false) cannot convey.

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

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

Core purpose is front-loaded and every sentence carries information for a genuinely complex authoring tool, but the single dense paragraph mixes capability catalog, syntax pointers, validation caveats, and two long mode-specific instructions without any structural breaks, making it heavier to scan than necessary.

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 7-param tool with an output schema, the description covers what an agent needs: what a body may contain, which format modes exist, which guide resources/tools to consult for exact syntax, and the post-write lint step. Return-value explanation is rightly left to the output schema.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: the body is markdown with wikilink/backlink semantics and a large valid block palette, and the free-form `props` object gains concrete documented keys (deck, variant, sheet) that the schema does not enumerate.

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?

Opens with a specific verb+resource+scope: 'Create a page in a space (editor+)'. It further distinguishes the tool from siblings by naming the follow-up/related tools (lint_page, deck_authoring_guide, sheet_authoring_guide) and the two property-driven modes (deck=true, sheet=true) that change what the body must contain.

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?

Gives explicit conditional routing: decks when asked for presentations/slides/talks, sheets when asked for spreadsheets/budgets/trackers, and mandate to call lint_page after writing. It does not state when to prefer this over siblings like update_page/patch_page, but the creation context is implied by the name and required params.

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 behavior beyond the annotations: the caller becomes owner with write scope, and slug is auto-derived from name when omitted. With readOnlyHint=false / destructiveHint=false already covering the safety profile, the remaining gap is silence on failure modes (e.g. name/slug collisions) and whether ownership is transferable.

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 core action and ownership effect come first, the routing guidance second; every clause 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?

For a 4-param create tool with a full schema and an output schema covering return values, the description supplies purpose, ownership semantics and sibling routing — enough to call it correctly. It stops short of noting collision/error behavior, but nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents name, slug, org_id and idempotency_key in detail. The description only restates the slug-derivation rule, which the schema also states, so it adds no meaning beyond structured data — 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?

States a specific verb+resource ("Create a space") plus the ownership consequence, which is more than a name restatement. It explicitly distinguishes itself from create_page and update_space, so an agent can route without opening sibling schemas.

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?

Gives an explicit when-to-use ("start a new top-level container of pages") and names two alternatives with the conditions that select them: create_page for adding pages to an existing space, update_space for renaming. Nothing is left to inference.

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?

Adds substantial context beyond annotations: editor+ auth requirement, atomic all-or-nothing batch semantics, that bad refs/ranges/sheets are rejected with a fixable error, and the return shape ('updated sheet with formulas computed'). Annotations only cover the read/write safety profile, so the description carries the informative load but doesn't cover rate limits or partial-failure edge cases explicitly.

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 the core distinction and the 'prefer over update_page' rationale before the op catalog. It is dense and longer than typical, but nearly every clause carries unique operational value; a slightly tighter op enumeration would be ideal.

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 complex nested-op mutation tool this is complete: it covers when to use it, the op vocabulary, atomicity, error behavior, default targeting, and points to sheet_authoring_guide for the full reference. With an output schema present, it correctly leaves return details to structured data while still noting formulas are computed.

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), and the description meaningfully exceeds it by enumerating every op kind with payload shapes (setCells, insert/delete rows/cols, setStyle, setFreeze, addSheet, renameSheet, deleteSheet), the 1-based/col-letter conventions, and the default-sheet behavior. It defers full syntax to sheet_authoring_guide, so it stops short of being exhaustive.

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

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

States a specific verb and resource ('Make a STRUCTURED edit to a sheet'), scopes it to sheet=true pages, and explicitly differentiates from update_page. An agent can distinguish it from patch_page/update_page without opening any schema.

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 routing: 'Prefer this over update_page for sheets' and it explains why (typed ops prevent corrupting formulas/grid by hand-editing text). It also names sheet_authoring_guide as the reference for advanced syntax, and states the 'op OR ops' selection rule.

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 explicit 'Read-only' line is mildly redundant. However, the description adds real behavioral context the annotations don't carry: it returns the page's full text in a fixed shape and hints that get_page supplies richer metadata and trust signals, which frames the trade-off.

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 tight sentences, front-loaded with the core purpose, followed by routing guidance. Every clause earns its place; nothing is padding.

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, return values need not be explained, and the description covers purpose, safety, and routing adequately for a single-parameter read tool. Nothing an agent needs to call it correctly is missing.

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 sole `id` parameter is fully documented in the schema. The description's note that the id 'comes from a search result' restates the schema wording rather than adding syntax, format, or edge-case detail, so the baseline 3 holds.

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

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

States a specific verb (fetch) and resource (a tela page's full text by id) and immediately distinguishes itself from both `search` (it is the fixed-shape companion) and `get_page` (same body, less metadata). An agent can select it without opening any schema.

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 routing: prefer get_page for normal use, and reach for `fetch` only when the host requires the fixed search/fetch contract. It names the alternative, the default choice, and the exact condition that selects this 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 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?

Annotations already declare readOnlyHint=true, so the description doesn't need to restate safety. However, it adds substantial behavioral context: it explains the epistemic block's trust signals (freshness, provenance, corroboration vs. dispute) and how to interpret them. This goes beyond the annotations, providing decision-making guidance.

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 the core return, then explains the epistemic block. Every sentence earns its place, though the second sentence is fairly dense. 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?

With an output schema present, the description needn't detail return values. It covers the key addition (epistemic signals) and their interpretation. Could mention pagination or size limits, but for a page retrieval tool it's largely 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%, so the schema already documents both parameters, including the format modes. The description adds no additional parameter semantics beyond what's in 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?

States a specific verb (get) and resource (page) with the exact return content (full markdown body + metadata for a numeric page id). The scope is precise and clear.

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

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

The description explains how to weigh the epistemic block, but does not explicitly state when to use get_page versus siblings like read_chunk, get_page_revision, or search. For a retrieval tool among many read alternatives, more routing guidance would help.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds useful context beyond that: the required access level ('editor+ on its space') and the trashed-page behavior. It could still note output format or whether historical bodies can differ structurally, but for a read tool this is solid added value.

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: the first defines the return payload and access requirement, the second gives the input source and the sibling alternative. No filler, and the payload definition is front-loaded.

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

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

An output schema exists, so return values need not be re-explained, and the description still names the key fields. With annotations, schema, and an output schema in place, the description covers the remaining gaps (access level, trashed pages, sibling routing) without redundancy.

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

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

Schema description coverage is 100%, with both parameters documented in the schema itself ('page the revision belongs to', 'revision id from list_page_revisions'). The description reinforces the revision_id provenance but adds no syntax or format detail 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?

States a specific verb and resource ('One historical revision of a page') and enumerates exactly what's returned: title, full markdown body, and properties as they were at that point. It distinguishes itself from get_page ('For the page as it is now use get_page') and from list_page_revisions ('Take revision_id from list_page_revisions').

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 routes the agent: it tells you where to get the input (revision_id from list_page_revisions) and names the alternative for the live page (get_page). It also adds the non-obvious condition that it works for trashed 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=true, destructiveHint=false and openWorldHint=false, so the 'Read-only' sentence largely repeats structured data. It adds no auth requirements, rate limits, or edge-case behavior (e.g. what happens for an unknown id), so it clears the lowered bar only marginally.

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 tight sentences: the operation and scope come first, then the routing guidance. Every clause earns its place with no filler.

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

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

A single-parameter read tool with an output schema, full schema coverage, and explicit safety annotations needs nothing more; the description supplies the one thing structured fields cannot, which is when to reach for this tool versus its siblings.

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

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

Schema coverage is 100% for the single id parameter, so the schema already documents it; the description's 'by id' adds only the framing that the id is a space id you must already possess. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (Fetch) and resource (one space's metadata) with the exact returned fields (id, name, slug) and the lookup key (by id). It is immediately distinguishable from list_spaces and list_pages, which it names explicitly.

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?

Gives an explicit when-to-use condition ('when you already hold a space_id and just need its name/slug') plus two named alternatives for the adjacent needs: list_spaces for discovery and list_pages for its pages. Nothing is left to inference.

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

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

Annotations already mark it as read-only and non-destructive. The description adds context about local conversion and the endpoint's contract, going beyond annotations. However, it does not mention any limitations or edge cases.

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

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

The description is front-loaded with purpose and usage, but the third sentence is slightly dense. Overall efficient, but not perfectly lean.

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

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

With no parameters, clear annotations, and an output schema, the description covers the tool's purpose, usage, and behavioral contract 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?

The tool has zero parameters, and the schema coverage is 100% (trivially). The description does not need to add parameter info; baseline for 0 params is 4.

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

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

The description clearly states it returns a guide for bulk-importing documents into a space as a page tree, specifying the types of documents and contrasting with manual page creation. It is specific and distinct from siblings.

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

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

Explicitly instructs to read this guide first for any import-related request, providing clear when-to-use guidance. Also outlines the dry-run, confirm, commit contract.

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?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=false, destructiveHint=false) by disclosing the two branching behaviors, the fact that an email is sent to a third party when no account exists, the auth constraint ('space owner only, write scope'), and the eventual auto-grant on signup. None of this is derivable from the structured fields.

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

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

Purpose is front-loaded in the first clause, and every sentence carries information (outcomes, role, alternatives). It is dense with caps and parentheticals, which is slightly heavy for a 3-parameter tool, but nothing is filler.

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

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

Given a mutation tool with an output schema, the description supplies everything the schema and annotations do not: prerequisites (space ownership/write scope), the outward email side effect, the conditional return shape, and the path to alternatives. An agent can invoke it correctly without further inference.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by restating the role enum with its default (viewer) and the owner-only restriction on space_id. That is useful reinforcement rather than new syntax-level detail.

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

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

States a precise verb+resource (give a person access to a space) and immediately narrows the mechanism to EMAIL ADDRESS, distinguishing it from sibling sharing tools. The response-shape summary ({member} vs {invite}) makes the two outcomes 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?

Explicitly says when to use it ('onboard someone who has no tela account') and when not to ('to add an existing user you already know by username, or to change/remove access, use the app's space sharing UI'). That is a direct routing rule away from alternatives, which is exactly what an agent needs.

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 establish readOnly/destructive=false and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the data is unanswered questions, the scope is constrained to the caller's own asks plus asks in spaces they belong to, implying a permission-bounded result set. No rate limit or pagination detail, but the scope note is valuable.

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

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

Two sentences, front-loaded with the core purpose then the scoping rule. The em dash aside ('a content roadmap: write these pages next') earns its place by conveying intended use, though the wording is slightly dense and mixes purpose with usage hint.

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?

An output schema exists so return values needn't be described, and annotations cover the safety profile; all three params are schema-documented. The description supplies the conceptual scope and ownership boundary, leaving only minor gaps like result ordering or practical limits for a tool of this 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 description coverage is 100%, so the schema already documents limit, space_id and since_days. The description only re-touches space_id and the since_days window and omits 'limit' entirely, adding no syntax or semantics beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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?

Names a specific resource ('the most-asked ask-your-docs questions the corpus could NOT answer') and frames it as a content roadmap, which is a distinct, non-obvious resource in a sibling set dominated by page/search/mutation tools. An agent can tell this is an analytics-style list of unanswered questions rather than a search or page tool.

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 phrase 'write these pages next' implies the intended follow-up action, but there is no explicit when-to-use vs when-not, no prerequisite stated, and no alternative sibling (e.g. search, suggest_links, find_overlaps) is named or excluded. Usage is implied rather than directed.

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, destructiveHint=false, openWorldHint=false, so safety is covered structurally. The description adds real behavioral context beyond that: the detection scope (rendered-vs-source divergence), the fact that issues are silent/invisible to re-reading, and that it is a diagnostic rather than a fixer is implied by 'check'. It does not state whether results are page-wide or whether any remediation is offered, keeping it at 4 rather than 5.

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?

Purpose is front-loaded in the first clause, with the triggers appended afterwards. The enumeration of failure modes is long but each item is a concrete, distinct diagnostic case rather than filler, so it earns its length – though it could be tightened without loss.

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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. The description supplies the problem domain and the timing cue, which is sufficient for a one-parameter read tool. It leaves minor ambiguity about result granularity (page-wide vs per-section), which keeps it from a 5.

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 one parameter at 100% schema description coverage, the schema already explains 'id of the page to check'. The description adds no further parameter detail (no scope/range/format options), so the baseline 3 applies – the schema carries this dimension.

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?

Names a specific verb and resource ('Check a page') and defines the exact class of problem: divergence between rendered output and markdown source. The enumerated failure modes (unknown :::block, silently unwrapping callouts, dropped raw HTML, missing wikilinks, broken attachments, ragged/overflowing tables) make it unmistakably distinct from sibling diagnostic tools like lint_deck or preview_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?

Gives an explicit trigger ('Run it after writing or editing a page') and pre-empts a likely alternative ('re-reading it is not a substitute for calling this'). It does not name or rule out sibling tools such as preview_page, find_overlaps, or suggest_links, so the routing guidance stops just short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value by explaining the semantic difference between share_url (preview page, chats unfurl) and download_url (raw bytes) and by flagging the `embedded` marker, but it says nothing about ordering, pagination, or empty results.

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 purpose is front-loaded, but the bulk is a single run-on enumeration of return fields (name, mime, size, three URLs, markdown, embedded). Because an output schema exists, most of that enumeration duplicates structured data; only the share_url vs download_url clause clearly 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?

With full schema coverage, safe-read annotations, and a published output schema, an agent has almost everything needed to call this correctly. The remaining gap is tool-selection guidance against list_space_files and the upload/delete attachment siblings.

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 (page_id) and schema description coverage is 100%, so the schema already documents it fully. The description adds nothing about the identifier's form; baseline 3 applies.

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

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

Specific verb+resource: 'List the files attached to a page' with an explicit scope qualifier ('uploads AND rclone-synced files'). This distinguishes it from raw file tools, but it never names the nearest sibling (list_space_files) or contrasts scope with it, so sibling differentiation is only implicit.

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?

There is a useful consumer hint ('give THIS to a person') about share_url vs download_url, but nothing about when to choose this tool over list_space_files, get_page, or the attachment-upload tools. No prerequisites or exclusions are stated.

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 read-only and non-destructive. The description adds value by detailing the link types checked and that it shows incoming references, which is helpful 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 concise sentences: the first defines the tool's exact behavior, the second provides usage context. No wasted words, 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?

The description fully covers purpose, usage, and link types for a simple tool with one parameter. Output schema exists, so return values need no elaboration. Complete for the given 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% and the single parameter 'page_id' is self-explanatory. The description does not add new parameter semantics beyond what the schema provides, matching the baseline.

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

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

The description clearly states the tool lists incoming references via specific link types ([[wikilink]] or tela://page/{id}), and explicitly distinguishes it from the sibling tool 'related_pages' which handles semantically similar non-linking 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?

Provides explicit guidance on when to use (to see dependencies before edit/delete, or walk link graph) and when not to (for semantically similar pages, use related_pages), including a named 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 readOnly/non-destructive, and the description layers on real behavioral context: editor+ permission requirement, roots-vs-replies shape difference between the two modes, cursor polling semantics including edited-activity and full-context returns, and the anchor plain-text caveat. These are traits the annotations do not cover.

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 the core verb, then modes, polling pattern, anchor caveat, and related tools in a logical sequence. Despite its length, every sentence carries operational meaning and none restates the schema verbatim.

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, return values need no explanation, yet the description still clarifies the shape difference between modes. Combined with annotations covering safety, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by tying page_id/space_id to their result shapes ('drill into the page for the replies') and framing since as a cursor-returned polling token. The anchor explanation enriches result interpretation though it maps to no parameter.

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

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

States a specific verb+resource ('Read comments') and immediately distinguishes the two operating modes: page_id for full threads (root + replies) vs space_id for a cross-space inbox of roots only. An agent can tell this apart from sibling reads like get_page or search without opening the schema.

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 which parameter selects which behavior, what status values mean, how to poll with cursor→since, and routes follow-up actions to add_comment(parent_id=…) and update_comment(resolved=true). This is when-to-use guidance plus named 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 read-only/no-destructive, and the description adds substantial beyond-that context: when revisions are snapshotted (every title/body change, by a person, agent, sync or Atlas), that it works on trashed pages, and how paging works. It also discloses the response shape including revisions being metadata-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?

Four dense sentences, front-loaded with what the tool returns and followed by scope, snapshot behavior, trash support, paging, and the alternative tool. No filler or repetition.

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

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

Given an output schema exists, the description needn't explain return values yet chooses to characterize them (page with deleted_at/current_revision_id; revisions metadata fields). Combined with permissions, snapshot timing, and trash behavior, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents limit and cursor. The description nonetheless clarifies cursor semantics in context ('Page back with cursor = next_cursor'), adding modest value beyond the schema's own wording.

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?

Opens with a specific verb+resource+scope: 'A page's revision history, newest first', and immediately distinguishes itself from get_page_revision by noting that sibling only reads one revision's full text. An agent can select this tool without opening any schema.

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?

States the access requirement ('editor+ on its space'), an explicit alternative for full revision text ('Read one revision's full text with get_page_revision'), and a concrete motivating case ('Works for trashed pages too, so you can recover what a removed page said'). When-to-use and the alternative path are both spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds useful context beyond that: the listing is 'flat' (no recursive expansion) and the parent_id-omit behavior changes which level is returned. It stops short of describing pagination or result limits, but it is well ahead of a bare read-only flag.

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 tight sentences: purpose and read-only first, then the parent_id scoping rule, then routing to alternatives. Every clause carries information and the load-bearing constraint is front-loaded.

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

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

An output schema exists, so return shape need not be described, and the safety profile is fully carried by annotations. The description covers scope, the key parameter's effect, and sibling routing — nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents space_id, status, and parent_id. The description restates the parent_id omit-for-top-level rule rather than adding syntax, defaults, or formats beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb ('listing') and resource ('pages') plus the scope ('in a space', 'flat'). It distinguishes itself from search and get_page by name, so an agent can route correctly without opening a schema.

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?

Gives explicit use cases (browse a space's structure, find a page_id) and names the two alternatives with the conditions that select them: `search` for keyword lookup and get_page for reading a body. No inference required.

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 cover the safety profile (readOnlyHint, destructiveHint=false), and the description layers on context annotations cannot express: required authorization level ("any space role"), a hard result cap of 500 files with a `truncated` signal for detecting truncation, and the shape of each entry including which fields are optional.

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 purpose and sibling differentiation, then payload shape, then filter syntax, then limits — a logical order with no filler sentences. It is dense and packs several clauses per sentence, which is justified by the information delivered but leaves little breathing room.

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?

An output schema exists, yet the description still names the meaningful return links (download_url, share_url, parent_page_id/parent_title) and the truncation flag, so an agent knows both what it gets and when output is partial. For a two-parameter read tool with full annotation and schema coverage, nothing material is missing.

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 already 100%, so the baseline is 3, but the description adds real semantics beyond the schema: the "absent = space root" convention on parent_page_id/parent_title, and the reserved literal "root" as a filter value. It stops short of documenting space_id behavior, but the incremental value over the schema is genuine.

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?

Opens with a specific verb+resource ("List every file stored in a space") and immediately scopes it against the closest sibling, list_attachments, naming the exact class of files only this tool can surface (root-parented, synced/imported). An agent can route between the two without opening either schema.

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

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

Explicit when-to-use ("the only way to discover a file that was synced or imported beside the page tree") and when-not ("invisible to list_attachments, which is per-page"), plus a concrete filtering recipe for parent_page_id. Nothing is left to inference.

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

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

Annotations already provide readOnlyHint and destructiveHint. Description adds that it returns id/name/slug for all accessible spaces. No further behavioral details needed for this simple tool.

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

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

Two concise sentences. First states purpose and return fields, second provides usage guidance. No 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?

For a zero-parameter tool with annotations and output schema, the description covers purpose, return content, and when to use it, making it fully adequate.

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

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

No parameters, so baseline score of 4 applies. No need for additional parameter context.

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

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

States it lists all accessible spaces, returning id/name/slug, and is read-only. Clearly distinguishes from get_space for single known spaces.

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

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

Explicitly advises to start here for discovering a space_id before using list_pages/search/create_page, and recommends get_space for a single known space.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds value beyond that: the dual-space Editor+ permission requirement (source AND target) and the mutual exclusivity between make_root and parent_id — neither is in 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, no filler. The move semantics and their parameter mappings come first, and the constraint follows immediately. Every clause carries information.

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

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

For a 5-parameter mutation tool with an output schema in place, the description covers the operation set, permissions, and the at-least-one-parameter rule, so nothing critical is missing. It could still be richer about what happens to existing children or ordering when space_id changes, but the output schema and annotations absorb most of that burden.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents each parameter's meaning. The description adds a constraint not encoded in the schema — that at least one of the four movement parameters must be supplied — which meaningfully guides correct invocation.

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

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

The description gives a specific verb (move) plus the four distinct sub-operations (reparent, detach, reorder, relocate) and maps each to its parameter, so the agent understands the exact scope. It stops short of naming how it differs from siblings like update_page or patch_page, which also mutate pages.

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

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

It states a real prerequisite (Editor+ in both source and target space) and a call constraint ('provide at least one of space_id / parent_id / make_root / position'), which is genuinely useful. However, it never says when to prefer move_page over update_page or patch_page, so the routing decision remains implicit.

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 substantial context beyond the annotations: the permission requirement ('editor+'), the isolation guarantee ('never touches the rest of the document'), and the side effect ('Snapshots a revision like any edit'), which also implies edits are recoverable. This is meaningful behavioral disclosure for a mutation tool whose annotations only give the readOnly/destructive flags.

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 tight sentences, front-loaded with the core scope claim, then the required workflow, then the comparative justification. The parenthetical '(editor+)' packs a permission requirement into two tokens; no sentence is wasted.

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?

An output schema exists, so return values need no explanation, and the full-coverage parameter schema handles the input details. The description covers the remaining gaps an agent needs: permission level, workflow ordering, side effects, and comparison to the sibling tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds procedural meaning to the 'target' parameter by tying it to the get_page format:"map" workflow. It does not add syntax detail for content, operation, base_version, or idempotency_key beyond what the schema already documents.

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

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

States a specific verb and resource ('surgically edit ONE section of a page') and immediately scopes it against the whole-body alternative ('instead of rewriting the whole body'), naming update_page and get_page so the agent can differentiate from siblings without opening schemas.

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?

Gives explicit when-to-use ('instead of rewriting the whole body'), names the alternative tool and the condition that favors it ('cheaper and safer than update_page on a long page'), and states a prerequisite workflow ('First call get_page format:"map" ... then patch the target'). Nothing is left to inference.

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=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior: it is the same render used by PDF export, and callouts, tables, math, mermaid and diagrams are resolved, plus what each format value returns. It stops short of noting render cost, latency, or output size for image/both, which is a minor gap.

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-loads the core purpose, then usage, then parameter semantics, then the sibling routing note — a sensible ordering with little waste. The dense em-dash clauses make it slightly heavier than necessary, but every sentence carries distinct 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?

There is no output schema, so the description carries the return-value burden, and it does: text reads the page back as plain text, image returns a screenshot, both returns each. Combined with the routing note and render-behavior context, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining the intent of each format value ('text ... enough to catch prose that the renderer swallowed or reordered'). It also confirms the default, which the schema states more tersely.

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

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

States a specific verb+resource ('render a page and read it back as the reader actually shows it') with the key differentiator that it uses the same render pipeline as PDF export. It explicitly names the sibling it is not for deck pages ('call preview_deck instead'), letting an agent disambiguate without opening any schema.

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?

Gives concrete when-to-use conditions: verifying that written content renders as intended, and re-checking after any edit whose result can't be inferred from markdown alone. It also supplies the negative case (deck pages → preview_deck), so routing is fully determined.

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 cover the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description adds real context beyond that: it works on both page and file chunks, and it names the file-chunk citation fields (file_name, parent page_id, download_url, share_url) an agent will encounter. It does not discuss error cases or missing-chunk behavior, keeping it short of a 5.

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 the core purpose and the granularity/alternative rule before the file-chunk detail. The parenthetical file-citation list is dense but earns its place as invocation-relevant context; slight wordiness keeps it from a 5.

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?

An output schema exists, so return values need not be explained, and the description still covers granularity, the alternative tool, the source constraint, and the file-chunk case. For a one-parameter read tool this is complete enough to call correctly.

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

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

There is a single parameter and schema description coverage is 100%, so the schema already documents chunk_id fully. The description's phrase 'from a `research` source' roughly restates the schema's 'chunk id from a research result' and adds no format or sourcing detail beyond it. 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?

States a specific verb+resource ('Fetch one chunk's full section text by chunk_id') and pins down the scope ('for a page OR a file chunk'). It also explicitly distinguishes itself from get_page ('Middle granularity... for the whole page use get_page'), so an agent can route correctly without opening either schema.

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?

Gives an explicit when-to-use ('expand a single cited section'), an explicit when-not/alternative ('for the whole page use get_page'), and a source precondition ('from a `research` source'). Nothing about selection is left to inference.

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 description adds that it uses stored vectors without a live embedder, offering useful operational detail.

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 front-loaded purpose, 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?

With an output schema present, description covers purpose, usage guidelines, and operational details sufficiently for a simple tool with two parameters.

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, so baseline 3 is appropriate; description does not add substantial new meaning beyond the schema.

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

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

Description clearly states the tool finds semantically related pages ranked by similarity, distinguishing it from list_backlinks which finds 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 says to use for topically similar pages and to use list_backlinks for pages that explicitly link, providing a clear 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 only cover the safety profile (readOnly=false, destructive=false, openWorld=false). The description goes well beyond them: the URL is short-lived, bytes never traverse model context, the exact call sequence (this → host PUT → read response or confirm_attachment_upload), the permission level, and the host's outbound-PUT requirement.

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-loads the purpose and constraint before the flow, and every clause carries information (limits, ordering, alternatives, prerequisites). It is dense and runs long as a single block, but nothing is wasted.

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, return values need no prose explanation. The description still supplies everything an agent needs to act correctly: prerequisites, sequencing, the follow-up tool, and where the resulting snippet goes (update_page/patch_page).

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

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

Schema description coverage is 100%, so all three parameters (name, page_id, mime) are already documented in the schema. The description references put_url/share_url, which are outputs rather than inputs, and adds no syntax or format detail for the parameters themselves. 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?

States a specific verb and resource ('Get a short-lived signed PUT URL to upload a file') and immediately differentiates itself from the sibling upload_attachment by the 5 MB inline cap and context-bloat rationale. An agent can distinguish it from upload_attachment and confirm_attachment_upload without opening any schema.

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 selection criteria: use this for files over upload_attachment's 5 MB inline cap or to avoid context bloat. It also names the fallback ('otherwise use upload_attachment') and the host capability prerequisite, plus the Editor+ requirement.

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

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

Annotations only cover the safety profile (readOnly, non-destructive, closed-world), and the description adds substantial behavioral context beyond them: full bodies rather than fragments, coverage of pages and attached files, surfaced `disagreements` and `low_confidence`, and critically the meaning of `truncated: true` (per-call cap, not exhausted corpus). The embedder/503 dependency is a valuable non-obvious runtime trait.

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-loads purpose before going into return shape and drill-in routing, and most sentences are functional (truncation semantics, prerequisite, citation by [n]). It is dense and slightly over-enumerates return keys (`context`, `sources`, `disagreements`, `considered`), some of which duplicate the output schema, but the overall organization is purposeful.

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, return-value explanation is optional, yet the description still supplies the semantics an agent needs: how to cite ([n]), how to drill in (chunk_id/download_url/share_url), and how to interpret `truncated`. Combined with the embedder prerequisite and sibling routing, nothing necessary for correct invocation is missing.

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 schema already documents `question`, `space_id` and `limit` (default 12, max 40). The description nonetheless adds actionable semantics for `limit` — raise it before concluding anything is missing when `truncated` is true — which links the parameter to observed behavior rather than just restating its bounds.

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

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

States a specific verb+resource+mechanism: answer/gather on the wiki "by MEANING," with the scope (full page bodies, pages AND attached files) made explicit. It cleanly distinguishes itself from siblings by naming `search` as exact-term lookup and positioning itself as the semantic alternative.

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 routing: use this when you need answer-ready grounding, `read_chunk` to read one section deeper, `get_page` for a full page, `search` for exact-name/term lookup. It also states the operational prerequisite — a configured embedder is required (503 otherwise) — and tells the agent how to react to truncation.

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?

Annotations already cover readOnly/destructive/openWorld, but the description adds genuine behavioral context beyond them: results are ranked and snippet-highlighted, and the tool 'works WITHOUT an embedder (always available)', which tells the agent about availability guarantees. It does not mention pagination or result-cap behavior, so a 4 rather than 5.

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 the mechanism before usage and the alternative. All content is relevant, though the parenthetical '(always available)' and the embedder clause make the third sentence slightly denser than needed.

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?

An output schema exists, so return-value explanation is unnecessary. The description covers what the tool searches, when to prefer it, how to narrow scope, and the key availability caveat — complete for a read-only search tool of this 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 description coverage is 100%, so all three parameters are already documented in the schema. The description restates that space_id narrows to one space but adds no syntax, format, or ranking-tuning detail beyond what the schema provides — 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?

States a specific mechanism (keyword/full-text lookup over title + body) with concrete output behavior (ranked, snippet-highlighted). It explicitly contrasts itself with the `research` sibling by meaning vs. exact-term matching, so an agent can discriminate without opening schemas.

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?

Gives a clear when-to-use ('find a page you can name or that contains an exact term/identifier/error string') and an explicit when-not with the named alternative ('to answer a question or gather material on a topic by meaning, use research instead'). Nothing is left to inference.

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.