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

Discloses that the author is the API token's owner (auth implication) and that threads are one level deep (behavioral constraint). No output schema or annotations, so description carries behavioral burden; could mention return value, but adequate.

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

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

Two efficient sentences covering action, parameters, auth, and usage. No unnecessary words, all sentences add value. 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 no output schema or annotations, description covers purpose, parameters, auth, and use case. Lacks mention of return value or error conditions, but sufficient for a simple comment creation 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 descriptions already cover parameters well (100% coverage). Description adds nuance by explaining nodeId vs parentId distinction and thread depth, providing extra meaning beyond schema.

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

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

The description clearly states 'Post a comment on a diagram' with specific verb and resource. It distinguishes from siblings like list_comments and create_diagram by detailing node vs. parent parameters and threading behavior.

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 for when to use ('leave structured review findings') and notes threading depth. Does not explicitly list when not to use or alternatives, but effectively implies using list_comments for reading.

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?

No annotations provided, so description carries full burden. Clearly discloses that findings are returned and that setting postAsComments: true persists them as comments on the diagram, including node-pinning behavior.

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

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

Two concise sentences. First states purpose and output, second explains optional flag. No superfluous text.

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

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

No output schema, but description lists types of findings. Could elaborate on exact return format, but overall sufficient for a 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%, baseline 3. The description adds meaningful context for postAsComments, explaining its side effect beyond the schema description.

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

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

Clearly describes the tool's purpose: analyzing a stored flowchart diagram's structure and returning specific actionable findings (orphan nodes, hubs, cycles, etc.). Distinguishes from sibling tools like get_diagram or update_diagram.

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 that it is for flowchart diagrams only, providing clear context. Does not explicitly mention when not to use or alternatives, but the specificity 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states that the present URL is not shareable and only Space members can open it, and it details the alternative sharing method. It also notes the prerequisite that diagram ids must already exist. It does not mention any other side effects, but for a creation tool this is sufficient.

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

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

The description is a single, well-structured paragraph with the core action and primary parameter instruction front-loaded. Each sentence adds value, covering the flow, return values, and sharing caveat without redundancy. It is appropriately sized for the complexity of the tool.

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

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

For a tool with no output schema, the description covers return values (deck id and present URL), the non-shareability limitation, and how to share externally. It also specifies prerequisites and the typical usage flow. Nothing essential for an agent 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 description adds meaningful semantics beyond the schema: slides must be a complete ordered list, a diagram may appear at most once, and omitting slides creates an empty deck. It also explains the title's purpose and that description is optional. This goes beyond the schema's descriptions and significantly helps correct usage.

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

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

The description clearly states the tool creates a presentation deck from existing diagrams, with a specific verb and resource. It distinguishes itself from create_diagram by outlining the typical flow and implicitly from get_deck/update_deck by focusing on creation. The slideshow-order emphasis clarifies the core purpose.

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

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

It gives explicit when-to-use guidance: after creating diagrams, collect their ids, and pass them in order. It also instructs to use list_diagrams to find existing ids and explains how to share the deck outside the Space via the DiagramZu Share button. This is clear, actionable 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?

With no annotations, the description carries the disclosure burden and does it well: it explicitly warns that the returned URL is not a shareable link, explains the correct sharing workflow, and points to server instructions for diagram types and class role names. It does not exhaustively cover permissions or rate limits, but the most important behavioral caveat is clearly stated.

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

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

Three sentences, each earning its place: purpose and return value, the sharing caveat, and the pointer to selection instructions. There is no filler or repetition of schema details.

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

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

Given 6 parameters, a nested styleOptions object, and no output schema, the description supplies the critical return value, URL permission model, and sharing workflow. The schema covers parameter-level details, so nothing essential appears missing, though it could optionally mention auth requirements or default behavior more explicitly.

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

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

Schema coverage is 100%, with each parameter already described including defaults and enum options, so the baseline of 3 applies. The description adds only a general pointer to diagram-type selection and class roles rather than clarifying individual parameters, which is acceptable but not additive 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?

States a specific verb and resource ('Create a new diagram in the Space') and clarifies the return value (id and app URL). This cleanly distinguishes it from siblings like create_deck, update_diagram, and list_diagrams.

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

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

Provides clear context for when to use the tool (creating a diagram) and useful caveats about the returned URL being Space-member-only. It does not explicitly name alternative tools or state when not to use it, but the purpose is unambiguous enough that this is a minor gap.

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

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

With no annotations, the description carries full burden. It clearly indicates a read-only operation and discloses return fields. However, it omits details on error handling (e.g., behavior on non-existent id) and permissions.

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 verb and resource, achieving maximum conciseness for the information conveyed.

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

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

Despite lacking an output schema, the description lists return fields adequately. However, missing details on optional behavior (e.g., if deck not found) make it not fully complete.

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

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

Schema coverage is 100% and the description's mention of 'by id' adds no new meaning beyond the schema's 'Deck UUID'. Baseline 3 is appropriate as no extra semantics are needed.

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

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

The description clearly states the action ('fetch one deck by id') and the specific resource, and distinguishes from siblings by specifying the return fields (title, description, ordered slides).

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

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

The description implies when to use (to get a single deck with slides) but provides no explicit guidance on when not to use or alternatives, relying on sibling names for differentiation.

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

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

With no annotations provided, the description carries the full burden, and it does so well: it discloses the access restriction (URL openable only by Space members), the special 'Share (public, read-only):' line, that public links are minted by humans via the Share button, and the semantic meaning of the description field as the agent's brief. This is rich behavioral context for a read operation.

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 action and return values, then the public-link nuance, then the workflow tip. The 'minted by a person' explanation is slightly verbose but earns its place by clarifying that the agent cannot generate public links itself. 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?

No output schema exists, so the description correctly takes on the job of explaining the return shape (title, description, mermaid source, URL, public-link line). For a one-parameter fetch tool with no annotations, the access restriction, return format, and workflow guidance together make it 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?

Schema coverage is 100% and the schema already documents the single 'id' param as 'Diagram UUID'. The description only echoes 'by id' and adds no syntax or format details beyond the schema, so the 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+resource: 'Fetch one diagram by id', and enumerates the exact return values (title, description/mermaid brief, mermaid source code, app URL). The singular 'one...by id' clearly differentiates it from list_diagrams and from get_deck/get_version on other resources, so an agent can select it correctly 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?

Provides clear workflow context: 'Read the description before editing — it tells you what the diagram is for and when to update it', which routes the agent to inspect the diagram before calling update_diagram. It does not explicitly name alternatives or exclusion conditions (e.g., 'use list_diagrams to search'), but the single-id scope and the pre-edit instruction give usable 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?

With no annotations, the description carries the full burden. It explicitly states the tool is read-only and that restore is not available via API (human-only UI). This discloses key behavioral constraints beyond the schema.

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

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

Two sentences: first tells action and return data, second adds behavioral note. Every word earns its place; 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?

Despite no output schema, description specifies return fields (title, source code, metadata). With 2 simple params and clear behavior (read-only), the description provides sufficient 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% with descriptions for diagramId and versionId. The description adds 'Fetch one snapshot by id' but does not elaborate on parameter meaning or format beyond what the schema already provides.

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

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

Description clearly states 'Fetch one snapshot by id' and lists returned fields (title, mermaid source code, metadata). This specific verb+resource combination distinguishes it from siblings like list_versions (list all) and get_diagram (get diagram, not version).

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

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

Description includes 'Read-only — restore is human-only in the UI,' which tells the agent this tool is for retrieval only and not for restoring a version. However, it lacks explicit guidance on when to use this vs list_versions (e.g., when you need details of a single version).

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?

No annotations are provided, so the description carries the full load. It discloses the return fields (id, parentId, nodeId, etc.) and ordering, implying a read-only, non-destructive operation. It lacks details on pagination behavior beyond the schema, but the included information is sufficient.

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

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

The description is three sentences, all substantive. The first sentence introduces the action and ordering. The second lists key return fields. The third gives actionable parameter advice. No fluff or redundancy.

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

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

Given the tool has 5 parameters and no output schema or annotations, the description covers purpose, return structure, ordering, and parameter usage. It omits error behavior and pagination details, but the schema covers limit/offset. Overall, it is sufficient 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 is 100%, so baseline is 3. The description adds value by explaining that nodeId 'fetches only the thread pinned to one node,' reinforcing the schema description and providing practical usage context. Other parameters are not elaborated, but the addition warrants a slight bump.

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

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

The description clearly states the verb ('List') and resource ('comments on a diagram') and specifies ordering ('oldest first'). It distinguishes from sibling tools like add_comment (which creates) and others that deal with diagrams or decks. The purpose is unambiguous.

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

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

The description explicitly advises 'Use nodeId to fetch only the thread pinned to one node,' guiding when to apply that filter. It does not provide explicit contraindications or alternatives, but the advice is clear enough for effective 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?

With no annotations, the description carries full burden. It correctly identifies the operation as read-only (listing) and specifies the return fields. However, it doesn't mention potential behaviors like pagination, rate limits, or authentication, which are minor omissions for a simple list tool.

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

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

The description is extremely concise: two sentences that cover purpose, ordering, definition, and return fields. Every word adds value with no redundancy.

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

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

Given no parameters or output schema, the description fully covers what the tool does and returns. It explains the concept of a deck and the sorting, making it self-contained.

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% (0 parameters), so baseline is 3. The description adds no parameter info (none exist) but provides context on the return values, which is adequate.

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 decks in the configured Space with specific ordering (newest-edited first). It defines what a deck is and specifies the return fields, distinguishing it from siblings like create_deck or get_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?

The description implies usage for listing decks but does not provide explicit guidance on when not to use it or mention alternatives. For example, it doesn't say 'use get_deck for a single deck' or 'use list_diagrams for diagrams.' The context is clear but not directive.

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

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

With no annotations provided, the description must shoulder the behavioral disclosure burden. It accurately implies a read-only operation (listing) and details filtering and sorting behaviors. It explains default behavior ('newest first by default') and the `relevance` sort's behavior, adding valuable context beyond the schema. It does not discuss pagination or limits on the number of diagrams returned, which would be useful, but the provided detail is substantial.

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 efficient and well-structured, with the primary purpose front-loaded and additional guidance flowing naturally. It is about 3 sentences, each adding clear value (purpose, pre-create check, filter/sort guidance). It avoids fluff and is appropriately sized for the tool's functionality.

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

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

For a non-mutating list tool with no output schema and full parameter documentation, the description provides nearly everything an agent needs: default behavior, filtering, sorting options, and the important workflow context to avoid duplicates. However, it omits pagination or handling of very large result sets, which could be a gap in some scenarios, but that is a minor omission.

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 each parameter in detail. The description reinforces this by giving usage examples for `q` ('e.g. q: 'schema'') and explains the meaning of `sort: 'relevance'` ('title hit ranks above a description or code hit'). However, it adds little beyond what the schema already says, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'List diagrams in the configured Space (every folder, newest first by default).' It specifies the resource ('diagrams'), the scope ('every folder'), and the default ordering ('newest first'), which distinguishes it from siblings like list_folders and list_decks.

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

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

The description explicitly instructs when to use this tool: 'Use this BEFORE create_diagram to check whether a diagram with the target purpose already exists — if it does, prefer update_diagram over creating a duplicate.' It also gives conditional guidance for the `q` parameter ('when looking for a named diagram') and the `sort` parameter ('to find the most recently changed diagrams'). Alternatives (create_diagram, update_diagram) are named and conditions for preferring them are specified, meeting the highest standard.

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?

No annotations provided, but description discloses behavior: returns id and path, ordered by name, max two levels deep, human-only creation. Assures read-only nature.

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, front-loaded with main action, no wasted words, 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?

Complete for tool with no parameters and no output schema; explains return structure (id, full path) and nesting depth, covering all user needs.

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

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

No parameters in schema; baseline for 0 params is 4. Description adds value by explaining return fields, compensating for lack of parameters.

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

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

The description clearly states the tool lists every folder in the configured Space, ordered by name, and returns id and full path. It distinguishes from siblings by mentioning its use before create_diagram or update_diagram.

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 (before create_diagram or update_diagram), how to match by name, and that folder creation is human-only, providing clear guidance.

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

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

With no annotations, the description carries the burden. It discloses that only manual snapshots are listed, ordering is newest first, and specifies return fields. However, it doesn't mention pagination behavior or prerequisites like diagram existence, which are somewhat covered by schema parameters.

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 purpose and ordering, second lists return fields. No unnecessary words; information is front-loaded and efficient.

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

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

For a simple list tool with no output schema, the description covers core behavior and return fields. It could mention pagination handling or error conditions, but overall it is fairly complete given the tool's complexity.

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

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

Schema coverage is 100% with descriptions for limit and offset. The description adds no additional parameter semantics beyond what the schema provides, so baseline score applies.

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

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

The description clearly states the tool lists manual snapshots of a diagram, ordered newest first, and specifies the exact fields returned. It distinguishes itself from siblings like get_version (single snapshot) and list_diagrams (different resource).

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

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

The description implies usage when needing to list snapshots for a given diagram, but does not explicitly state when not to use it or provide alternative tools. While siblings offer context, no direct guidance is given.

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

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

With no annotations, the description carries the full burden and does so thoroughly: explains the declarative slides behavior (omitted ids removed, new ids appended), the return value (deck id and present URL), the URL's non-shareable nature, and the required sharing workaround. No side effects are left unmentioned.

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

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

Two sentences, front-loaded with purpose, then details on the most complex parameter, then return value and sharing. No wasted words; every sentence adds needed 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 tool has 4 parameters (1 required), no output schema, and no annotations. The description covers the tricky slides semantics, the return value, and the sharing caveat. The schema covers the simple parameters. 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%, so the baseline is 3. The description adds significant value by explaining the declarative semantics of the 'slides' parameter, which goes beyond the schema's description of 'complete ordered list'. This extra guidance justifies a 4.

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

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

States a specific verb and resource ('Update a deck') and enumerates the mutable fields (title, description, slide order). Clearly distinguishes from siblings like create_deck and get_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?

Provides clear context for when to use this tool (updating existing decks) and elaborates on how the declarative slides parameter works. Does not explicitly name alternatives or exclusions, but the context is sufficient to route correctly.

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?

No annotations are provided, so the description carries the full burden. It discloses a key behavioral trait: in proposal-enabled workspaces the change is a proposal and a review URL is shared. It also mentions class assignment preservation. However, it omits other important behaviors: what the tool returns (updated diagram or proposal URL), whether updates are fully overwriting or partial, and the semantics of createVersion/versionLabel (snapshotting). These gaps reduce 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?

The description is concise, starting with the purpose, then two important behavioral notes. It is front-loaded and each sentence adds value. It is not overly long and has no fluff, though it could be slightly tighter. A strong, efficient 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?

With 9 parameters, a nested styleOptions object, and no output schema, the description covers the core update action and the proposal edge case, but it does not explain return values or the behavior of createVersion/versionLabel, which are significant for this mutation tool. The absence of output schema means the description should clarify what the agent can expect back, but it does not. This leaves the definition incomplete for an agent to fully understand the tool's behavior.

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 documents all parameters. The description adds some value by specifying that when rewriting source, class assignments must be maintained, and it contextualizes the proposal workflow. However, it doesn't elaborate on individual parameters beyond what the schema provides. Baseline 3 is appropriate since the schema covers the semantics and the description offers only marginal additional meaning.

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

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

The description clearly states the verb 'Update' and the resource 'existing diagram', and lists the editable fields (title, description, mermaid source, visual style preset, layout style options). It is specific and distinguishable from sibling tools like create_diagram, though it doesn't explicitly differentiate itself from update_deck. No explicit sibling naming, but the purpose is unambiguous.

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

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

The description provides conditional usage guidance: it instructs to keep or restore class assignments when rewriting source, and explains that in a proposal-review workspace the change is recorded as a proposal rather than applied live, requiring the agent to inform the user and share the review URL. It does not name alternatives, but as it is the only tool for updating diagrams, the context is clear and sufficient.

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