Agentic Mermaid

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

The description discloses the return envelope in both success and failure cases, and notes a prerequisite (`describe_sdk`). Annotations already indicate readOnly, idempotent, and non-destructive behavior, so the description adds value by explaining the process of folding ops and the exact response shape.

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 long, front-loaded with the primary action, and each sentence earns its place: the core action, a clarifying analog, and the return/usage caveat. No wasted words.

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

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

No output schema exists, but the description fully covers the return values, error format, and necessary prerequisites. With only two parameters and good annotations, the description gives the agent enough to understand behavior and integration with siblings.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining that ops are 'folded' over an empty diagram, giving operational context beyond the schema's listing of `{ kind, ...fields }`. It also clarifies the role of `family` by naming it as the diagram type.

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: author a new Mermaid diagram from blank using structured ops. It distinguishes itself from siblings by being 'the declarative counterpart to hand-writing source' and returns the same envelope as `mutate`, implying a different operation from that mutation tool.

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

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

The description implies when to use this tool: when authoring a new diagram declaratively via ops rather than writing source directly. It also advises calling `describe_sdk` for unfamiliar ops. It does not explicitly name alternatives, but the reference to `mutate` and the broader sibling list provide enough context.

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

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

Annotations already establish read-only/idempotent behavior. The description adds value by disclosing the exact response shapes for each format and the deterministic nature of facts, which is beyond annotation coverage. No contradiction.

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

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

Three compact sentences, front-loaded with the verb+resource, and every clause adds functional detail (format behaviors, response shapes, example). No fluff.

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

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

Given the simple 2-parameter schema and idempotent/read-only annotations, the description fully covers expected behavior for all three formats, including return shapes. No output schema is present, so this return-shape documentation is essential and sufficient.

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 schema covers 100% of parameters, so baseline is 3. The description goes beyond schema by spelling out return objects for each format and giving a concrete fact example, though it does not add much to the 'source' parameter 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 states a specific verb and resource ('Describe a Mermaid diagram') and the format parameter clarifies three distinct output modes. This clearly differentiates from siblings like describe_sdk and render_*.

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 format-specific use context (e.g., facts for machine checking) but never explicitly states when to choose this tool over sibling tools such as render_* or verify. Usage is implied rather than directly contrasted.

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 the tool as read-only, idempotent, and non-destructive, so the description does not need to repeat that. It adds useful behavioral context by describing the two output modes and the version-matched nature of the returned operations, which goes beyond the basic safety profile.

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 long and every sentence earns its place: the first defines the core action, the second explains parameter choices, and the third gives invocation context. It is well-front-loaded and free of 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 lack of an output schema, the description does a good job of outlining what information will be returned (field types, required flags, enum values, defaults, constraints) and when to call it. However, it does not specify the exact return format (e.g., JSON), which is a minor gap for an agent that needs to parse the response.

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

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

The input schema already covers both parameters fully (100% schema description coverage), so the baseline is 3. The description enhances this by explicitly explaining the purpose of each 'detail' value and how they change the output, which helps the agent choose correctly.

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

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

The description clearly states the tool returns version-matched mutation operations for a specific diagram family. It distinguishes itself from the sibling tools by explicitly positioning it as a prerequisite for build, mutate, or execute, and the name 'describe_sdk' differentiates it from the generic 'describe' sibling.

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

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

Explicit guidance is provided: 'Call this before build, mutate, or execute when the family schema is not already known.' It also instructs when to use each detail mode ('signatures' for compact menu, 'fields' for exact types), making the usage context clear and actionable.

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

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

Annotations declare readOnlyHint=true, but the description adds substantial behavioral context: the sandbox is isolated, one call composes edits, promises/async/await/dynamic import/type annotations are unsupported, hosted runs cost more, and host policies force security:'strict' and embedFontImport:false. This goes far beyond what annotations provide.

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

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

The human-readable prose is concise, front-loaded, and well-structured. However, the SDK type declaration is extremely long and could overwhelm the model context for a tool-selection task. While useful as reference, it is not concise and includes many details that are not necessary for deciding when to invoke this 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?

This is a complex code-execution tool with no output schema. The description covers environment constraints, security policy, cost trade-offs, alternatives, and API surface. It gives an agent everything needed to determine if and how to use execute 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?

The input schema has 100% coverage for both parameters, so the baseline is 3. The description adds meaningful semantics for the 'code' parameter by documenting the complete mermaid.* SDK surface, which tells the agent what methods and types are available during execution. This is extra value beyond basic parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Run JavaScript in an isolated sandbox; return a value.' It clearly distinguishes the tool from siblings by stating that direct render/verify and declarative mutate/build tools should be preferred for simpler operations, positioning execute as the escape hatch for complex logic.

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

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

The description provides explicit when-to-use and when-not-to-use guidance, naming alternatives: 'prefer those for plain render/verify calls' and 'prefer the declarative mutate/build tools; reserve execute for logic the ops don't express.' This is exactly the kind of clear decision-making context needed.

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?

Even though annotations already declare the tool read-only and idempotent, the description adds crucial behavioral details: ops apply in order, are all-or-nothing, the first failing op stops the batch, and the input is left untouched. It also specifies the exact error shape and that `opIndex` indicates the failing op. No contradiction with annotations.

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

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

Every sentence contributes unique information: purpose, relationship to `execute`, usage guidance, return/error behavior, and op format. The description is detailed but tightly structured, front-loaded with the core purpose and followed by necessary qualifications.

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 fully specifies success and failure return shapes, the meaning of `opIndex`, and the all-or-nothing behavior. It also references `describe_sdk` for op signatures, making it complete for a complex mutation tool with a generic item schema. Sibling tool distinctions are clearly handled.

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 schema only defines `source` and `ops` generically, but the description adds essential semantics: each op is `{ kind, ...fields }`, ops are ordered, and the batch is atomic. It also explains how the parameters relate to the output and error handling, going well beyond the schema's 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?

The description leads with a specific verb and resource: 'Apply a list of structured edit ops to an existing Mermaid source and return the edited diagram.' It clearly distinguishes itself from the sibling `execute` by calling itself the declarative counterpart, making its role 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?

Explicit guidance is provided: prefer `mutate` for straightforward edits and reserve `execute` for logic the ops don't express. It also advises calling `describe_sdk` before authoring unfamiliar ops, giving clear when-to-use and when-not-to-use instructions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, lowering the burden. The description adds valuable behavioral context: return shape, concrete ASCII vs Unicode glyphs (+,-,| vs ┌,─,│), default behavior when useAscii is absent, and a typed error for impossible targetWidth bounds. There is no contradiction with annotations.

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

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

Three sentences, front-loaded with the core purpose, and each subsequent sentence adds essential behavioral detail. No filler or repetition of schema content; it is efficiently 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?

There is no output schema, so the description properly covers return shape and error behavior. It does not explain the extensive options object, but the schema already does, and the most terminal-relevant options (useAscii, targetWidth) are highlighted. This is complete enough for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful details beyond the schema: it shows exact ASCII characters, specifies that absent useAscii defaults to Unicode, and reveals the error condition for targetWidth. These enrich the schema's brief descriptions without redundancy.

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 'Render a Mermaid source string to text,' clearly identifying the verb, resource, and output format. It distinguishes from sibling renderers (render_png/render_svg) by specifically targeting text output and even states the return shape ({ ok, text }).

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 does not explicitly name alternatives, but phrases like 'to text' and 'terminal display-cell bound' make the intended context (plain text/terminal rendering) very clear. It stops short of explicitly saying 'use this instead of render_png/render_svg,' so it is not a 5.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable context: hosted rendering uses resvg-wasm with bundled fonts, bytes may differ from the local napi renderer, and the return shape is { ok, png_base64 }. This goes beyond the annotations without contradicting them.

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 with no fluff. The first sentence states the core purpose and return format, the second adds a critical determinism caveat, and the third points to an alternative for different artifact types. Every sentence earns its place.

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

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

Given the absence of an output schema, the description usefully states the return shape. It also covers the hosted/local distinction and determinism caveat. The schema is very rich and already documents all parameters. Minor gaps remain (e.g., error behavior, size limits), but overall the description is complete enough for an agent to invoke and interpret 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?

Schema description coverage is 100%, so each parameter already has a description. The tool description adds little new parameter-level meaning beyond confirming the source is a string and mentioning a distinction for file/URL artifacts. Since the schema carries the parameter burden, a 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 opens with a specific verb+resource: 'Rasterize a Mermaid source string to PNG.' It also states the return shape '{ ok, png_base64 }' and explicitly distinguishes this tool from image-byte determinism and the local stdio server, making its scope clear relative to sibling tools like render_svg and render_ascii.

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: this is the hosted PNG renderer for Mermaid source strings, and it warns that hosted output is not part of the byte-determinism contract. It also provides an exclusion: 'For file/URL artifacts use the local stdio server.' It doesn't explicitly name sibling tools like render_svg, but the guidance is sufficient for most selection decisions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral details beyond those: deterministic layout ('identical input produces identical geometry') and hosted-boundary constraints ('forces security:\'strict\' and embedFontImport:false'). No contradiction with annotations.

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

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

The description is three tight sentences: purpose, return shape, and behavioral constraints. It is front-loaded with the action and avoids redundant restatement of the title or annotations.

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 a very large options schema, the description captures the core behavior, return shape, determinism, and security constraints. It does not cover error behavior or supported Mermaid families, but the schema and annotations compensate for most gaps, and the absence of an output schema is mitigated by the explicit { ok, svg } return note.

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 only the phrase 'source string' and 'themeable SVG,' while the schema fully documents both parameters and all nested option properties. No additional semantic value is provided beyond what the schema already contains.

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 and resource: 'Render a Mermaid source string to themeable SVG.' It also names the return shape ({ ok, svg }), clearly distinguishing this tool from sibling renderers like render_ascii and render_png by output format.

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 that this tool produces SVG output, which differentiates it from ASCII and PNG rendering siblings. It does not explicitly name alternatives or provide when-to-use/when-not-to-use guidance, but the output-type framing is sufficient for basic selection.

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

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

The description goes beyond annotations by specifying the exact return shape for both success and failure, and it discloses a non-obvious behavioral nuance: ok:true does not guarantee the diagram is the intended type. This is critical for correct use and is not captured by the readOnly/idempotent hints.

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 compact and well-structured: it starts with the primary action, then the return format, and then the key caveat about interpretation. Every sentence earns its place without redundancy.

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

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

For a single-parameter tool with no output schema, the description is complete. It explains the return values, the distinction between structural validity and intent, and the warning codes. No critical information is missing for an agent to decide when and how to use this 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?

The input schema covers the single parameter 'source' with a description ('Mermaid source'), so schema coverage is 100%. The tool description adds no additional parameter semantics beyond what is in the schema, hence the baseline score.

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 'Parse and verify a Mermaid diagram without rendering it,' which pairs a specific verb with a resource and scope. It distinguishes itself from sibling render tools by explicitly excluding rendering, making its purpose unambiguous.

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

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

The description gives clear context for when to use this tool (verifying without rendering) and provides important guidance on interpreting the ok flag (check family and summary, as ok:true only means structural validity). It does not explicitly name alternatives, so it stops short of a 5.

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