Zindex

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

The description details key behaviors, such as returning IDs/hashes and retaining versions until deletion. However, it presents a significant behavioral conflict with the annotations; it describes content-based idempotency while the annotations set `idempotentHint: false`.

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

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

The description is well-structured, dedicating one sentence to output, one to the key constraint/idempotency, and one to the lifecycle. It is dense but logically paced.

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

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

Given the complexity of diagram management, the description is highly complete. It covers input formats, output identifiers, content constraints (idempotency), and version lifecycle management.

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

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

With 100% schema coverage, the description is not forced to explain data types, but it adds value by defining the *role* of inputs: `key` is defined as the stable, unique identifier, and `brief` is noted as storing context for future agents.

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 primary function: saving a new diagram from either a DSP scene or Mermaid text. This is distinct from sibling tools like diagram_edit or diagram_get, making the purpose unambiguous.

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

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

It implies the usage of creation and provides crucial context about how it behaves when the same inputs are repeated. While it doesn't explicitly list exclusions, the function name and context make its role 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 declare destructiveHint=true, but the description adds the details that actually matter: all versions are removed, undo is only available for 24 hours, and the tool prompts the user for confirmation. It also ties the 'confirm' parameter to a CONFIRMATION_REQUIRED flow. This is meaningful behavior beyond the annotation layer.

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, entirely front-loaded: what it destroys, how recovery works, and the confirmation requirement. No filler and no redundant restatement of the title.

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 destructive single-entity delete with no output schema, the description covers consequences, recoverability, and the confirmation gate. It leaves open how an undo is actually invoked and what the response returns (e.g., an undo token or confirmation state), which is a minor but real 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 67% and the description fills the main gaps: 'undo' restores within 24 hours (the boolean's semantics are otherwise opaque in the schema) and 'confirm' is described as a user-confirmation step. Only 'id' ('Diagram id or key') is left to the schema, which is acceptable.

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 ('Deletes a diagram') and adds scope ('with all its versions'), which is the key distinction from a hypothetical soft-remove. It does not explicitly compare itself to siblings such as diagram_edit or diagram_history, but the destructive intent is unmistakable against a set of create/find/get/render tools.

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

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

The 24-hour undo window implicitly signals that deletion is recoverable, which is useful decision context, but the description never states when to use this versus alternatives (e.g., archive vs delete) or any preconditions beyond confirmation. Usage guidance is present but inferred rather than explicit.

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 declare non-readonly, idempotent, non-destructive; the description supplies the substance behind those hints: an errored edit saves nothing (atomicity), a no-op edit returns noop, requestId makes a retry return the first result (the mechanism for idempotencyHint), and a conflict enumerates what changed. That is exactly the class of context annotations cannot carry.

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 revision/immutability fact, then the required inputs, then failure modes. Every clause carries information, but the heavy parenthetical stacking in one long block makes it denser to parse 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?

With an output schema present, return values need no prose, and the description covers atomicity, no-op, conflict, and retry semantics for this 8-parameter mutation. Remaining gaps are prerequisites such as permission requirements or whether validation is expected first, and how ops interacts with restoreRevision or brief beyond the mermaid constraint.

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 75%, and the description adds real meaning beyond it: baseRevision is the revision you last read (an optimistic-concurrency token, not just an integer), and mermaid is applied as a diff against the current view rather than replacing wholesale. It partly restates schema-documented text (one-line message, requestId example), which keeps it off a 5.

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 ("Changes a saved diagram") plus the key scope qualifier: it creates a new revision and old ones stay. That revision semantics alone distinguishes it from diagram_create (new diagram) and diagram_delete, so no sibling confusion is possible.

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 spells out the mutating modes and their mutual exclusivity: ops, mermaid (which cannot be combined with ops or restoreRevision), restoreRevision, or brief. That is concrete guidance for choosing an approach within the tool, though it never says when to reach for diagram_edit versus diagram_create or diagram_validate first.

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, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real value with result ordering (latest version first) and per-item contents (family, brief's first line), but says nothing about pagination behavior beyond the cursor parameter's own schema note.

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 that front-load the result set and ordering, then the search semantics. No filler clauses.

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 carries the burden of describing returns and does so (family, brief first line, version ordering). Pagination is only implied through the cursor parameter, leaving a small gap for a paged 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 coverage is 67%, with limit and cursor already documented; the description compensates on the undocumented query parameter by describing match fields, case-insensitivity, and ranking. It adds little about cursor or the limit maximum, but the important gap is filled.

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 ("Lists this workspace's diagrams") plus ordering and per-item return shape, so it is clearly distinct from diagram_get. It does not explicitly name the siblings it is not (e.g. diagram_get for a single diagram), so it falls short of full sibling differentiation.

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?

Explains what query searches (title, key, brief), that matching is case-insensitive, and that title matches rank first — clear guidance on how to use search versus a plain listing. It omits explicit when-not-to-use or alternative-tool routing.

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

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

The annotations already declare this as a safe, read-only, idempotent, closed-world operation. The description adds useful behavioral details beyond the annotations: the default outline shape, the scene JSON and Mermaid return forms, and the NOT_FOUND behavior for another workspace's diagram.

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

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

The description is front-loaded with the core action and then packs the important view and revision semantics into a compact paragraph. It is dense and could be easier to scan as a list, but every sentence carries useful information and there is 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?

There is no output schema, but the description adequately describes the default return structure and the alternate view outputs. It also covers the key error case, though pagination via cursor is only described by the schema and not by the description.

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 71%, so the schema documents some parameters already. The description meaningfully supplements this by explaining the semantic difference between 'revision', 'asOf', 'knownRevision', and 'elements', though it does not explain 'cursor' pagination behavior beyond what the schema provides.

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

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

The description opens with a specific verb+resource ('Reads a diagram') and then details what the default read returns, making the scope clear. It also distinguishes the mermaid view from diagram_edit by saying the Mermaid output is meant to be edited and sent back, so the agent can tell it apart from sibling mutation tools.

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

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

It explicitly explains the view modes ('outline', 'dsp', 'mermaid') and when each is useful. It also names the revision-selection parameters and their distinct purposes: 'revision or asOf reads an earlier version', 'knownRevision' shows only changes since a revision, and 'elements' limits output to those elements and neighbors.

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, idempotent and non-destructive, so the safety profile is covered; the description adds ordering ('newest first') and a full inventory of returned fields, which the agent could not infer otherwise. It stays silent on pagination behavior beyond what the cursor param implies, and on rate limits.

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

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

Two tight sentences: the primary behavior and its payload first, the alternative mode second. No filler, no restatement of the title, and the mode distinction is front-loaded where the agent will read it.

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, describing the returned fields and their order is exactly the right compensation, and the compare branch is at least characterized. The compare result itself ('what changed') is left vague, and pagination semantics for cursor/limit are left entirely to the 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 75%, and the description adds genuinely new semantics: compare's from/to accept 'revision numbers or dates', which the schema only types as integer-or-string without explaining. 'to' defaulting to latest is repeated from the schema, and limit/cursor get no prose, but the schema covers them adequately.

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 ('Lists a diagram's versions') and enumerates the returned fields (time, by, client, message, chain hash, change counts), so the agent knows exactly what this produces. It also separates the tool's two modes (list vs. compare). It never names a sibling such as diagram_get or diagram_render, so sibling differentiation is left 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?

The final clause routes the agent between the tool's two modes: use the base call for a version list, use compare 'instead' to learn what changed between two versions. That is an explicit alternative with a selecting condition. There is no guidance about when to prefer this over siblings like diagram_get or diagram_find.

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: link expiry rules (7 days vs until revoked/private/deleted), NOT_FOUND behavior, no sign-in for version links, share links omit title, and preview adds a PNG. Annotations only establish read-only/idempotent safety, so this extra operational context 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?

The description is dense but front-loaded and has no filler; the key output and link behavior come first. However, telegraphic fragments such as 'url is its page' and 'Others last 7 days' reduce clarity.

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 and annotations present, it covers the key operational context: link lifetime, auth, error behavior, preview, and unsaved diagrams. A few short phrases remain ambiguous, but the definition is sufficient 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 high at 86%, so the baseline is 3, but the description adds meaningful semantics for preview, scene/mermaid vs id, and version-link ids. It leaves asOf, revision, and knownRevision to the schema, which is acceptable given the coverage.

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 that it returns SVG/PNG links for a diagram version rather than image bytes, including size, date, hashes, and engine version. It distinguishes version, published, and share link behavior, though the description itself never uses the verb 'render' and only indirectly contrasts with sibling tools.

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

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

Gives concrete selection guidance: use scene or mermaid instead of id to preview an unsaved diagram, add preview for a PNG, and note that artifacts, slides, and PDFs need the PNG file itself. It also explains link lifetimes and auth differences, but does not name sibling tools or state explicit when-not-to-use conditions.

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 destructiveHint=true and openWorldHint=true, the description discloses the exposure scope ('readable by anyone at its link', 'showing its images, not its scene', 'revokes them all') and that data leaves the system to Zindex support/staff. It also flags the confirmation gate for four actions, which the annotations do not convey. It doesn't state reversibility of unpublish or what the confirm token flow returns.

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

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

Compact and action-ordered, front-loading the four sharing verbs before the two support verbs, with zero filler. The semicolon-chained clauses are dense enough that a fast reader may mis-parse where one action's semantics end and the next begins.

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 12-parameter destructive multi-action tool with no output schema, the description covers the actions and confirmation gate but leaves the feedback/report payload fields (expected, observed, confidence, anonymize) and the confirm token mechanics unexplained. An agent could pick the right action but would still guess at how to fill several 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?

At 58% schema coverage, the description compensates for some gaps: it explains the 'docs' kind meaning, that id or snippet attaches a diagram, and that report targets one version (implying revision). It says nothing about expected, observed, confidence, or anonymize, leaving several maxLength-bounded fields undocumented in both places.

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?

Each of the six actions is given a specific verb+effect (publish makes readable at its link, unlink revokes all links, report sends one version to support), so an agent knows exactly what this tool does per action. It does not differentiate the tool from siblings like diagram_get or diagram_render, which would require a single framing sentence about sharing vs. reading.

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

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

The per-action semantics effectively encode when to choose each action, and the closing sentence names which actions trigger a user confirmation (publish, link, report, feedback), which is real selection guidance. It stops short of explicit exclusions or cross-references to alternatives such as diagram_history for version inspection.

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, idempotentHint and destructiveHint=false, so the description is free to spend its words on the return contract, which it does: ok/errors/warnings plus code, offending element, and one-line fix. It does not state what happens if neither or both inputs are supplied (both are optional), which is the one behavioral hole.

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 filler, and the single most decision-relevant fact ("without saving it") is placed up front. The second sentence delivers the return shape compactly in one clause chain.

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?

Because there is no output schema, the description correctly spends its second sentence explaining return values, and the nested scene object is delegated to an external schema URL in the input schema. The gap is that neither parameter is required, and the description doesn't say whether exactly one input must be provided or how the two are combined.

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 mermaid property already carries the erDiagram/flowchart limitation note, so the schema does the heavy lifting. The description only names the two input kinds ("DSP scene or Mermaid text"), adding no format or size detail beyond the structured fields; 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 ("checks") over a specific resource ("DSP scene or Mermaid text") and adds the scoping qualifier "without saving it," which separates it from diagram_create and diagram_edit. An agent can pick it out of the diagram_* family 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 phrase "without saving it" implies a pre-save validation workflow, which is useful context, but the description never names an alternative or an explicit when-not-to-use condition. There is no guidance on using this before diagram_create versus after diagram_edit, so usage is only implied.

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