GraphMake

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

Annotations already declare readOnly, idempotent, non-open-world, so safety is covered. The description adds behavioral value the annotations cannot: with no output schema present, it discloses the actual return shape, the key/value format, and that preview=true additionally returns a preview image.

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

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

Two sentences, no filler. The core purpose and return format lead, followed by the actionable handoff to render_template and the optional preview behavior. 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?

With no output schema, the description carries the burden of explaining return values, and it does so concretely with example keys and values. It covers the required id implicitly (via list_templates reference) and the optional preview flag, leaving nothing an agent needs to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description goes further by showing the concrete key syntax ('w0.text', 'w5.datasets.0.values') that ties the returned keys to the values expected by render_template. It also restates the preview toggle's effect (returning the preview image), adding marginal meaning beyond the schema.

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

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

States a specific verb and resource ('Read one template') plus precisely what it returns: size, description, and every editable text/number as field keys with values, including concrete examples ('w0.text', 'w5.datasets.0.values'). This is clearly distinguishable from the plural list_templates 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?

Explicitly routes the agent forward: 'Copy the keys you want to change into render_template,' which names the alternative tool and the next action. It also explains when to set preview=true. It stops short of stating when NOT to use this tool (e.g. for listing or bulk reads), so it's clear context but not full when/when-not coverage.

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 openWorldHint=false, so the safety profile is covered structurally. The description adds that this is a comprehensive reference ('full... language reference') and that it should precede script authoring, which is useful sequencing context. Minor gap: no note on format (static text vs. fetchable sections).

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, front-loaded with the resource and scope, followed by the imperative. 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?

For a zero-parameter, read-only reference tool with no output schema, the description supplies the key facts: what it contains and when to call it. A note on output shape (returned as text vs. structured sections) would complete it, but it is largely 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?

Zero parameters, so there is nothing to document; baseline is 4. The description does not introduce spurious input expectations, which is correct for a no-arg reference tool.

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 resource: the full GraphMake Script language reference, and enumerates its scope (widgets, charts, themes, sizes, syntax). Clearly distinct from siblings like get_template and list_templates, which are template retrieval operations, not language documentation.

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 directive: 'Read it before writing a script.' Gives a clear trigger condition for use. Stops short of naming alternatives or exclusions, but the directive is unambiguous for the primary use case.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and idempotentHint=true, so safety and determinism are covered. The description adds that the query ranks matches, which is behavioral context not in annotations, though it doesn't discuss pagination or default ordering when no query is given.

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

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

Three tight sentences with no waste; the primary purpose is front-loaded, followed by usage guidance and the next step.

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 two-parameter, read-only list tool with no output schema, the description is nearly complete: it states what is returned, how filtering works, and the next action. It could mention pagination or default behavior if any, but nothing essential is missing.

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

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

Schema coverage is 100%, so the parameter definitions already document both query and category. The description adds value by giving concrete query examples ("sales report", "timeline", etc.) that clarify the expected input style, slightly above the baseline 3.

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

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

States a specific verb (List) and resource (GraphMake's designed infographic templates), and even enumerates the fields returned (id, name, category, size, what it is for). This clearly distinguishes it from sibling get_template, which retrieves a single template by id.

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

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

Explicitly tells the agent how to use the query parameter to rank results and names the next step: 'Then call get_template with an id.' This provides clear when-to-use and workflow context relative to sibling tools.

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 readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered structurally. The description usefully clarifies that the tool produces a URL rather than rendering bytes, but adds nothing about return format or any limits. Adequate, not 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?

A single front-loaded sentence that states what is built and when to use it, with no filler. Every clause earns its place.

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

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

For a one-parameter, read-only tool with no output schema, the description conveys enough: the action, the artifact (editor URL), and the user intent that triggers it. Minor gap is that it never says what is returned to the caller explicitly.

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

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

Only one parameter with 100% schema description coverage, so the schema already explains 'script'. The description's phrase 'script already rendered on the canvas' adds the meaning that the script is parsed and displayed, but no format or syntax detail beyond the schema.

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

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

States a specific verb and resource: builds a GraphMake editor URL preloaded with the script rendered on the canvas. It contrasts implicitly with sibling render tools by framing the output as an editor URL, though it never names an alternative 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?

Gives clear triggering context ('for when the user wants to hand-edit, restyle or export the infographic'), which tells the agent when this tool is the right pick. It stops short of naming alternatives such as render_infographic or stating when not to use it.

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 openWorldHint=false, and the description adds real value beyond them: it discloses the return payload (image plus an editor link for hand-editing/export) and the error behavior ('Parse errors name the line'). It stops short of covering size limits or latency, so not 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, then the syntax primer and the retry instruction. The inline syntax examples are somewhat lengthy but earn their place by reducing the chance of a malformed script, and each sentence carries a distinct instruction.

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 correctly compensates by explaining what is returned (image + editor link). Combined with the error-recovery hint and the pointer to the reference tool, an agent has enough to call and recover from failures; only edge cases like dimension limits are left 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 description coverage is 100% — width, height, format and script are all documented in the schema, including the png/svg enum. The description reinforces the PNG/SVG distinction but adds no syntax or constraint 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 ('Render') and resource ('GraphMake Script into an infographic image (PNG or SVG)'), which cleanly separates it from render_template (template-based) in the sibling list. An agent can select it without opening the schema.

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

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

Explicitly routes the agent: 'Call graphmake_script_reference first if you have not seen the full syntax,' naming a real sibling and the condition that selects it. It also implies the retry loop on parse errors, though it does not explicitly say when to prefer render_template instead.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, openWorldHint=false), so the bar is lower, and the description still adds real behavior: sample content is preserved for untouched fields, replaced items inherit the colours of the item they replace, and the return is an image plus an editor link.

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, followed by examples that each earn their place by demonstrating a distinct case (scalar, list, nested dataset). Slightly dense with multiple inline JSON snippets, but no filler sentences.

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 the mutation semantics, the defaulting behavior that could otherwise cause silent surprise, and the return payload (image + editor link) despite there being no output schema. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% (baseline 3), but the description goes beyond it by showing the actual key syntax ('w0.text', 'w5.datasets.0.values') and the nested list-item shape with colour inheritance — details the schema's one-line 'Field key -> new value' does not provide.

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 ('Render a template filled with your content') and immediately clarifies the mechanism via the 'changes' map. It implicitly routes the agent: keys come from get_template and the id from list_templates, which distinguishes it from the sibling read/list 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 operational guidance: omitted fields retain sample content ('so replace all of it') and list lengths are changed only by replacing the entire list. It does not explicitly say when to prefer this over render_infographic, so it stops short of full alternative routing.

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