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

No annotations, so the description carries full burden. It discloses that the author is the API token's owner, that threads are strictly one level deep, and that nodeId is only for top-level comments – key behavioral facts. It stops short of describing permissions needed, editability, or notification behavior, which keeps it from 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 tightly packed sentences, all front-loaded and zero waste. Every clause conveys necessary information.

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

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

For a comment-creation tool with no output schema and no annotations, the description covers author attribution, threading depth, and node pinning rules. It omits return value details (expected, as no output schema), and doesn't mention rate limits or whether comments are editable, but those are minor against the core operation.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description reinforces nodeId/parentId semantics and the threading constraint but adds no syntax, format, or validation details beyond what the schema says. 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?

Specific verb+resource ('Post a comment on a diagram') and distinguishes itself from siblings by naming the pinning and threading capabilities. An agent can pick this apart from list_comments 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?

The description gives clear context for when to use each parameter combination ('Pass nodeId to pin...', 'parentId to reply...') and states the intended context ('structured review findings a human will see'). It doesn't mention alternatives like list_comments or when not to comment, but the usage 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?

No annotations are provided, so the description carries the full burden. It usefully discloses the mutation side effect: default behavior is ephemeral prose, while postAsComments:true persists comments on the diagram surface (node-pinned when a finding names a single node). It omits permissions/auth requirements and any rate or cost considerations, 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?

Front-loaded with the core action and the list of findings, then the flowchart-only restriction, then the optional flag. Every sentence earns its place, though the final sentence is long and could be tightened.

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 3-parameter tool with no output schema, the description names the return contents (orphan nodes, over-connected hubs, cycles, disconnected clusters, grouping suggestions) and covers the optional write path. Nothing an agent needs to invoke 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 description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the effect of postAsComments (persisting findings as comments) and the node-pinning behavior, which the schema does not mention.

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 (analyze) and resource (stored flowchart diagram's structure: nodes, edges, subgraphs) and enumerates the concrete findings returned. The 'Flowchart diagrams only' restriction further distinguishes its scope 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?

Gives a clear condition for the optional behavior ('Set postAsComments: true to also persist...'), but does not name an alternative tool or state when analysis should be preferred over, e.g., get_diagram. No sibling tool offers structural analysis, so the absence of explicit alternatives 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 the full burden and delivers: it discloses the return values (deck id and present URL), a critical access constraint (only Space members can open the URL, it is NOT shareable), and the out-of-band sharing path via DiagramZu's Share button. This is exactly the non-obvious behavioral context an agent needs.

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 action and the slides contract, then the flow, then the return/sharing caveat. Dense and mostly waste-free, though the sharing explanation runs slightly long for a single tool description.

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, and the description compensates by explaining what is returned (deck id, present URL) and its access limitation. Combined with the prerequisite chain, an agent has everything needed to call this 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%, so the schema already documents space, title, slides, and description including the ≤200/≤1000 char limits and the 'at most once' rule. The description reinforces the ordered-list semantics but adds little 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 ('Create a presentation deck from existing diagrams') and immediately names the source objects, distinguishing it from siblings like create_diagram and update_deck. An agent can tell exactly what this produces.

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 typical flow (create_diagram per slide → collect ids → create_deck in presentation order), names the prerequisite (ids must already exist in this Space, use list_diagrams), and routes the sharing use case to a separate mechanism. When-to-use and alternatives are fully covered.

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 real work: it discloses that the returned URL is Space-member-only, is NOT shareable, and that a public link requires an in-app Share action. It does not cover creation-time permissions, failure modes, or rate limits, but the visibility semantics are unusually well documented.

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 value, and the sharing caveat is worth its length because misuse produces a link that silently fails for outsiders. The Share-button walkthrough is somewhat verbose, but every sentence conveys a distinct constraint.

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-parameter, annotation-free tool with a nested object and no output schema, the description fills the two biggest gaps itself: return shape and link visibility. Remaining omissions are error behavior and creation permissions, which are secondary for a first-call 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 genuine meaning beyond the schema by pointing at the class role names (edge/core/data/accent/muted) for color-grouping in the Mermaid code and by explaining what the description field is for. The nested styleOptions object is left to 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?

Opens with a specific verb and resource scoped to a Space ('Create a new diagram in the Space'), which is clearly distinguishable from siblings like create_deck or update_diagram. It also states what is returned (id and URL), so an agent knows the outcome 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?

It routes the agent to the server instructions for diagram-type selection and explains the sharing workflow, but never states when to prefer this over alternatives such as update_diagram or when creation would be refused (e.g. duplicate names). Context is clear, but explicit exclusions are absent.

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 usefully discloses the return shape (title, description, ordered slides as diagram id + title), but says nothing about permissions, error behavior for an unknown id, or whether the space parameter affects visibility. Some value added, but gaps remain for a tool with zero annotation coverage.

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 with the operation front-loaded and no filler. Slightly dense parenthetical about slide structure, but every clause conveys real 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 simple read tool with a fully documented schema and no output schema, the description covers purpose and return contents well. The only missing piece is behavioral context around permissions or failure modes, which is minor here.

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 both parameters (id, space) are fully documented in the schema, including the space fallback and ambiguity-refusal rules. The description adds nothing beyond what the schema already states, which is the correct baseline 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 deck by id), and the second sentence clarifies it retrieves a single deck rather than a collection, distinguishing it from list_decks. An agent can identify the operation 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?

Usage is implied by 'one deck by id' versus the sibling list_decks, but there is no explicit when-to-use statement, no mention of prerequisites, and no routing guidance to alternatives. Adequate but leaves inference to the agent.

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 provides substantial behavioral context: it describes the returned fields, notes that the app URL is restricted to Space members, explains the public link and how it is minted, and advises reading the description before editing. It does not cover error cases or required permissions for the call itself, but it is otherwise rich.

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

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

The description is front-loaded with the core action and return values, and every sentence contributes useful information. It is slightly longer than strictly necessary due to the public-link detail and editing advice, but there is no redundant or wasted language.

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 retrieval tool with no output schema, the description compensates by detailing exactly what is returned, including the public link format, and adds a workflow hint about reading the description before editing. It is complete enough for an agent to call the tool correctly and understand the output.

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 input schema already fully documents both parameters (id and space). The description adds no additional syntax, format, or constraint details beyond what the schema provides, making the baseline score of 3 appropriate.

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

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

The description states a specific verb ('Fetch') and resource ('one diagram by id'), and it lists the exact return fields (title, description, mermaid source, URL), clearly distinguishing it from list-oriented siblings like list_diagrams or analyze_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?

The description implies usage by saying 'Read the description before editing — it tells you what the diagram is for and when to update it,' which suggests this tool is for retrieving a diagram prior to an update. However, it does not explicitly state when to use this tool versus alternatives like get_version or analyze_diagram, nor does it provide exclusion criteria.

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 does disclose the safety profile (read-only) plus the fields returned (title, mermaid source, metadata). It omits error behavior for a missing or inaccessible id and any permission requirements, which keeps it from 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?

Two short sentences, zero waste, with the identity of the operation front-loaded and the return contents and read-only constraint following. Nothing could be cut without losing information.

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

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

With no output schema, the description usefully enumerates the return fields, and the read-only constraint covers the safety dimension that annotations would otherwise supply. Error handling and permission requirements remain unstated, a minor gap for a simple single-item read.

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 space parameter is documented in detail in the schema, including fallback behavior and name-collision handling. The description only says 'by id', adding no syntax or format detail beyond what the schema already provides, 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 and resource ('Fetch one snapshot by id') and immediately distinguishes itself from list_versions by scoping to a single snapshot. An agent can pick it apart from get_diagram and list_versions 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?

The 'restore is human-only in the UI' clause tells the agent what this tool cannot be used for, which is genuinely useful routing guidance. It stops short of explicitly naming list_versions as the alternative for enumeration, so it lands just under the top band.

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 behavioral disclosure burden. It usefully enumerates return fields (id, parentId, nodeId, author, resolved state, body snippet) and ordering, but omits read-only nature, required permissions, rate limits, and pagination behavior, leaving significant gaps.

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 with no filler, front-loading purpose, then return shape, then a usage tip. Efficient, though slightly less crisp than the ideal two-sentence 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?

No output schema exists, so the description's explicit return-field list is valuable. The schema fully covers parameters, and the description adds ordering and nodeId usage. Some behavioral context (e.g., default pagination, space parameter implications) is missing, but the definition is adequate for a list 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 description coverage is 100%, so the schema already documents all six parameters thoroughly. The description adds only a minor rephrasing for nodeId and provides no additional semantic detail for other parameters, matching the baseline for high-coverage schemas.

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 ('List comments on a diagram') plus an ordering guarantee ('oldest first'). However, it does not differentiate itself from sibling tools like add_comment or other list_* tools, so it falls short of a 5.

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 a specific usage instruction for the nodeId filter ('Use nodeId to fetch only the thread pinned to one node'), which is helpful. But it offers no guidance on when to use this tool versus alternatives (e.g., add_comment) or when not to use it, leaving usage implied.

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

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

No annotations are provided, so the description carries the full burden. It does disclose ordering (newest-edited first) and the shape of each returned item (id, title, slide count), which is genuinely useful. It omits pagination/result-limit behavior, permission requirements, and whether an empty Space is possible — notable gaps for a list endpoint with zero annotation coverage.

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 short sentences, front-loaded with the action and scope, then the definition, then the return shape. No filler and nothing that could be cut without losing information.

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

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

For a read-only list tool with no output schema, the description supplies the essential missing piece — what each returned item contains — plus scope and ordering. It falls short only on pagination/volume behavior and authorization expectations, which an agent would want before paging through results.

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

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

The single 'space' parameter has 100% schema description coverage, including slug/name/id forms, the default-workspace behavior, and the ambiguity refusal rule. The description adds nothing beyond the schema here, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List presentation decks'), scopes it ('in the configured Space'), and adds the ordering ('newest-edited first'), which is enough to separate it from get_deck, create_deck, and update_deck. It also defines the domain object ('an ordered set of existing diagrams shown as a slideshow'), so the agent knows what a deck is without external context.

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

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

Usage is implied by 'list ... in the configured Space' and by the return of id/title/slide count, which signals a browsing/enumeration purpose. However, it never says when to prefer get_deck over this, nor any exclusion or prerequisite, leaving routing 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?

With no annotations, the description carries the full burden and does disclose defaults: scope is the whole Space across every folder, and ordering is newest-first by default. It omits result limits, pagination, and any auth/scope caveats, which are meaningful for a list endpoint.

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 and default behavior, then layers the pre-create check and filter/sort guidance. It is somewhat long, but each sentence carries actionable routing or parameter 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?

Covers scope, ordering defaults, and the pre-flight duplicate check for a 5-parameter, all-optional list tool. Given no output schema and no annotations, the omission of pagination/result-size behavior is the remaining gap.

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

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

Schema coverage is 100%, so both `q` and `sort` are already fully documented in the schema; the description largely restates that (substring match, relevance ranking). It adds only light usage framing rather than new semantics, 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+resource (list diagrams) plus scope (configured Space, every folder) and the default ordering. It also distinguishes itself from siblings create_diagram and update_diagram by naming them, so an agent can route 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?

Explicitly instructs to run this BEFORE create_diagram to avoid duplicates and to prefer update_diagram when a match exists. It also names the conditions for using `q` and each `sort` value, leaving little 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?

With no annotations, the description carries the burden and does disclose two real constraints: folders are at most two levels deep, and folder creation is human-only. It does not cover permission/auth requirements or behavior for spaces with zero folders, so it stops short of full disclosure.

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, all load-bearing: scope/return shape, then the workflow instruction, then the two structural limits. The most actionable content (use before create/update) is front-loaded after the scope statement.

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

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

For a simple one-param read tool with no output schema and no annotations, the description covers scope, return fields, nesting depth, downstream usage, and the human-only limitation on creation. Nothing an agent needs in order 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% for the single 'space' parameter, and the schema description already explains id/slug/name resolution and the ambiguity refusal. The description adds no parameter-level detail beyond the phrase 'configured Space', 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 ('List every folder in the configured Space') plus the ordering and the returned fields (id and full path with a concrete example). It is clearly distinguishable from siblings like list_spaces 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?

Explicitly names the downstream tools (create_diagram, update_diagram), the precondition ('use this BEFORE'), and the intended workflow (match a folder by name and pass its id as folderId). This is a model example of routing 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, and it does useful work: it defines the semantics of the default workspace and explains that a single-scoped connection returns only one entry. It does not address pagination or rate limits, but for a zero-parameter read-only listing the disclosure is solid.

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 short sentences, front-loaded with purpose, then return shape, then the routing instruction, then the edge case. No sentence 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?

No output schema exists, and the description compensates by naming the returned fields; no annotations exist, and it still conveys safety implicitly via 'list' plus the scoping behavior. An agent has everything needed to call it and use the result.

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. The description does add cross-tool semantics by explaining that the returned id is passed as `space` on other tools, which is context the empty schema cannot convey.

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 ('List every workspace this connection can act in') and enumerates exactly what comes back (id, slug, name, role, default flag). This is clearly distinguishable from the diagram/deck siblings in the tool set.

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 triggers ('Call this FIRST when the user mentions a workspace by name, or when you are not sure which workspace the work belongs in') and names the follow-up action (pass the id as `space`). It also pre-empts the trivial case of a single-workspace connection.

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 behavioral burden and does reasonably well: it discloses sort order, enumerates the returned fields (id, label, title, createdAt, createdBy), and the word "manual" signals that autosaved versions are excluded. It stops short of stating pagination behavior or any 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?

Two short sentences, zero filler, with the scope and ordering front-loaded before the return-shape sentence. 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?

There is no output schema, and the description compensates by enumerating the fields returned per snapshot, which is exactly the right disclosure. Remaining gaps are minor: it does not describe what "manual" excludes or how pagination interacts with limit/offset.

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 limit, offset, space, and diagramId are already fully documented in the schema. The description adds nothing about parameter behavior, so the baseline of 3 applies.

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

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

States a specific verb (List) and a precise resource (manual snapshots of a diagram), plus the sort order (newest first). The word "manual" usefully narrows scope, implicitly distinguishing these snapshots from autosaves, though it never names the sibling get_version as the single-item 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?

Usage is implied by the verb and the required diagramId, but there is no explicit when-to-use guidance, no mention of when to prefer get_version, and no stated prerequisites (e.g., permission to read the diagram).

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 well: it discloses the destructive/additive semantics of `slides` (omitted ids are removed, new ids appended) and clarifies that the returned present URL is members-only, not a shareable link, plus how to actually share. It does not state the permissions/auth required to perform the update, leaving 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?

Purpose is front-loaded in the first sentence, followed by the non-obvious `slides` contract and the return/share caveat. It is somewhat long and the sharing explanation could be trimmed, but every sentence carries information relevant to correct invocation or interpretation.

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 and no annotations, so the description must cover behavior and return values, and it does explain the return payload (deck id + present URL) and its sharing limitation. The main residual gap is the absence of permission/prerequisite information for a mutation tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine meaning beyond the schema for `slides` by spelling out the declarative contract (full-list replacement, reorder/add/remove, append order) and reiterating omit/[] behavior, which goes past 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?

States a specific verb (update) and resource (deck) and enumerates the updatable fields (title, description, slide order). An agent can immediately distinguish this mutation tool from get_deck, create_deck, and list_decks without consulting 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?

The description explains how to express reorder/add/remove via the declarative slides list, which is strong implied usage guidance for that parameter. However, it never states when to choose this tool over siblings (e.g., create_deck vs update_deck) or any prerequisites for invoking it, so usage guidance is present but partial.

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 largely succeeds: it discloses the proposal-review approval flow (a non-obvious side effect that changes whether the edit is live), the color-grouping requirement for source rewrites, and the 'and/or' semantics implying partial updates. It does not cover permission/workspace requirements or failure modes, which keeps it out of 5 territory.

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 purpose, then the two most consequential behavioral caveats. Nothing is filler, though the sentences are dense and could be trimmed slightly.

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 10-parameter mutation tool with a nested styleOptions object, no output schema and no annotations, the description covers the critical unknowns: that fields are optional/partial, that a proposal may be created instead of an immediate write, and the source-rewrite constraint. Missing only auth/workspace prerequisites, which the schema's `space` description partially handles.

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

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

Schema description coverage is 100%, so the schema already documents all 10 parameters in depth (code byte limit, space resolution rules, enum meanings, versionLabel/createVersion interactions). The description mostly restates the field list and adds only the cross-reference to role names for `class` assignments; 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 opens with a precise verb+resource ('Update an existing diagram') and enumerates the mutable surface (title, description, mermaid source, style preset, layout options). The resource is unambiguous against the sibling update_deck, and an agent can route correctly 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?

It gives real conditional guidance: keep/restore `class` assignments from the server instructions when rewriting source, and in proposal-review workspaces the change becomes a pending proposal — with an instruction to inform the user and share the review URL. It stops short of naming explicit alternatives (e.g. create_diagram vs update, or reading with get_diagram first).

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