chartlink

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

The title and description both assert this is a dry run that creates nothing, while the annotations declare readOnlyHint=false and destructiveHint=true. That is a direct conflict about whether the call mutates state, which is the single most important fact for an agent deciding to invoke it.

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, front-loaded with the check performed and its outputs, closing with the usage cue. No filler, though the output enumeration is dense enough that it could be slightly trimmed.

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 declared, the description usefully previews what is reported back (unmatched values, closest codes, grey count, scale), so an agent knows what a successful call yields. The contradiction with the annotations about state mutation is the only real completeness 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 description coverage is 67% and the nested schema already documents columns, rows, dateFormat, and the template identifier in detail. The description adds 'No key needed' (an auth note) and confirms the data/knobs are the same payload passed to create_from_template, but contributes little about the parameters themselves.

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 gives a specific verb+resource ('Matches every region value against the template's geography and reports...') and names concrete outputs: unmatched values with closest real codes, grey-region count, and the map scale. It is unmistakably distinct from create_from_template, which it names as the follow-up action.

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 states exactly when to reach for it ('Use it when unsure of the codes') and routes to the alternative explicitly ('then create_from_template with the same data and knobs'). The relationship between this tool and its sibling is fully specified.

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 (readOnlyHint=false, destructiveHint=false) establish a non-destructive write, and the description adds real behavioral context beyond them: publish makes URLs live in the same call, a success means it 'validated AND rendered,' and bad region values return a 400 listing closest codes before creation. It does not spell out permissions or overwrite semantics, but the added detail is substantial.

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

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

The content is dense and mostly earns its place, but it is delivered as one long run-on paragraph with no structural breaks, and the first sentence is atmospheric rather than front-loading the purpose. Parameter-critical details (knob types, map column order) are buried mid-paragraph.

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 no-output-schema, nested-object write tool this covers most of what an agent needs: validation-before-creation behavior, the publish lifecycle, preview-on-success, and error format. Minor gaps remain around required-permission context and non-region validation failure modes.

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 already 100%, but the description adds genuine meaning the schema cannot express: it enumerates actual knob names/values (theme, dataType, map colors, etc.), explains the two-column map data convention, the config deep-merge order, and publish's iterate-vs-live semantics. It does defer to get_template for the full knob schema, so it is helpful rather than exhaustive.

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 name and title make the action clear (create a chart from a template), and the body reinforces it by referencing 'the template's design, your data' and routing to list_templates/get_template for inputs. The first sentence is evocative rather than a plain verb+resource, but the overall intent is unambiguous and distinguishable from siblings like get_template and check_template_data.

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 concrete workflow guidance: 'omit [publish] while you iterate,' use get_template for knob schema, use list_templates for ids, and explicitly states region validation comes back as a 400 'before anything is made — no separate check needed,' which routes the agent away from check_template_data. No explicit when-not-to-use statement, but the context is strong.

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 readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds meaningful behavioral context beyond annotations: it explains the tool returns a contract bundle, doubles as a prerequisite for create_from_template, and accepts three different identifier forms. This is useful behavioral detail without contradicting the 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 long but every sentence carries distinct information: the prerequisite relationship, the contract contents, and the identifier formats with real examples. It front-loads the most important operational fact ('Read this before create_from_template') and is structured for an agent to understand the tool's full value at a glance.

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 carries the burden of explaining return content, and it does so thoroughly: looks, knobs JSON Schema, column roles, region-code convention with lookup URL, dataType expectations, and an example call. It also covers the input forms and provides concrete usage examples, making it complete for a single-parameter retrieval 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 schema already documents that id can be a template id, slug, or page address. The description adds value by giving concrete examples such as 'sweden/municipalities, us/texas/counties, london/wards' and explaining that knowing the place lets you bypass list_templates. This goes beyond the schema without being redundant.

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: 'Returns the template with `contract`' and enumerates exactly what that contract contains. It also distinguishes itself from siblings by saying users can 'skip list_templates when you know the place' and by explicitly being a prerequisite to create_from_template.

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

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

It gives explicit usage guidance: 'Read this before create_from_template' establishes when it should be used relative to that sibling, and 'skip list_templates when you know the place' clarifies when not to use the discovery tool. The description names the alternative and the condition that selects this tool.

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 provide read-only and idempotent safety, and the description adds genuinely useful behavior: results are ranked, each result carries urls.png and required columns, and template ids are usable downstream. It does not discuss matching mechanics or empty-result behavior, but that is minor for a safe search operation.

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

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

Four sentences carry a lot of signal without padding: template naming, result contents, how to pass q, and the downstream create_asset step. Key usage instructions are front-loaded and 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?

Even without an output schema, the description conveys the return shape enough for an agent: a ranked list of templates with urls.png, columns, and template ids. It omits minor edge cases such as empty search results, but the workflow and data contract are sufficiently clear for this read-only search 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 schema already documents all four parameters with 100% coverage, so the baseline is 3. The description adds value beyond the schema by explaining q with natural-language examples and clarifying that results are ordered best-first, which reinforces the purpose of the limit parameter.

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 and title clearly identify list_templates as a search/discovery tool: templates are keyed by the need they answer, and passing q returns a ranked list with the instruction to take the first. This distinguishes it from get_template or create_from_template by framing it as the discovery step before asset creation.

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 an explicit workflow: form q from the person's words, take the top ranked hit, then hand the template id to create_asset; it also notes that any already-known chart id can be used as a template, implying when listing is unnecessary. It does not explicitly name alternative sibling tools like get_template or state when not to use this tool.

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 flag destructiveHint=true, so the agent knows this is an irreversible write; the description adds that embeds are updated everywhere and that history is pinned at '?v=N'. However, it never warns about the destructive/irreversible nature beyond the pinned-version aside, nor explains the two argument-relevant behaviors it implies (re-embedding downstream copies).

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, front-loaded with the state change and then the return-value guidance. Phrasing like 'Returns urls:' is telegraphic and relies on the reader to infer the field names, but no sentence is wasted.

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 tells the agent how to consume the returned urls (embedIframe vs png/page on Substack) and the pinned-version pattern. It remains incomplete on the mutation's consequences and on the undocumented 'note' parameter.

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 only 33% (only 'premium' is documented), so the description is expected to compensate for 'id' and 'note' — it does not mention either. The return-shape guidance is about outputs, not inputs, leaving two parameters semantically empty.

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 opening 'Makes the draft live' states a clear verb and effect, and the title adds that it snapshots a version and updates every embed. It conveys what happens but never names the resource type (asset/brief) as precisely as its siblings update_asset or create_edit_link do.

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 — you call this when the draft is ready to go live — but the description never says when to publish vs. update_asset, nor describes prerequisites or exclusions. Nothing routes the agent between siblings.

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 are all false (readOnlyHint, openWorldHint, destructiveHint), so they carry no information. The description fills this gap by disclosing that reports are fixed same-day when they contain a proper description, and that title-only reports cannot be acted on. This is a useful behavioral expectation beyond the schema, though it doesn't describe side effects or error handling.

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 two sentences, ~50 words, with the core purpose front-loaded and the key usage rule ('one report per distinct issue') placed immediately. No redundant phrasing; every clause adds value.

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 4-parameter tool with low schema coverage and no output schema, the description should cover all essential semantics. It covers when to use, what to include in the description, and expected outcome, but it leaves 'type' and 'assetId' unexplained (the schema provides only the enum and name). This is a noticeable gap for an agent constructing a proper request.

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 only 25% (only 'description' has a schema description). The tool description adds meaning to the 'description' parameter (what you tried, expected, happened) and implies that 'title' should be concise, but it does not explain 'type' or 'assetId'. Since the description must compensate for low schema coverage, this partial coverage is insufficient for full parameter clarity.

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 explicitly states the tool's purpose: recording issues when a capability is missing, a schema fights you, or docs are wrong. It uses a specific verb ('record') and resource ('the owner'), and clearly distinguishes from sibling tools which all handle asset/data operations, not feedback.

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 clear conditions for when to use the tool ('If a capability is missing, a schema fights you, or docs are wrong') and provides actionable guidance: 'One report per distinct issue' and the requirement for a 'real description' with what you tried, expected, and what happened. Since no alternative feedback tool exists, this is sufficient 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?

Annotations already flag destructiveHint=true, but the description goes far beyond them: recursive object merge, wholesale array replacement, null-clears-key, ordering of config before configPatch, data replacing rows wholesale, expectedVersion/409 conflict handling, and the non-obvious fact that updates do not publish by default.

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?

Dense but every sentence carries operational content — merge behavior, removal path, concurrency, publish default. The first sentence is long and front-loads a specific parameter's semantics rather than the tool's purpose, which costs a point on front-loading.

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 9-parameter, nested-object mutation tool with no output schema, the description covers merge/replace semantics, concurrency, and publish behavior well. The inline preview image return is only mentioned in the title, and brand/title/showcase are untouched, leaving minor gaps.

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 56% schema coverage across 9 params, the description meaningfully compensates: it explains configPatch vs config interaction and precedence, data semantics, publish, and the expectedVersion requirement. id, brand, and title get no explanation, but they are largely self-evident, so this is above baseline.

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 reads as an update tool with clear resource semantics (draft config, data rows, publish state) and specifies the two mutually exclusive update modes, configPatch vs config. It never states the base purpose in a single plain sentence — the title carries 'Update a draft' — but the specific verb/resource is unmistakable from the body.

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 routing: use configPatch to send only changes, use config when you must remove keys, fetch current state via get_asset, and publish_asset separately if you don't pass publish:true. It also states the 409 recovery path (re-merge onto returned current), which is exactly the when-to-use guidance an agent needs.

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, so the safety profile is covered. The description adds useful context beyond annotations: it explains that all writes are stamped with createdBy/updatedBy = key name, helping the agent understand why verifying the key first matters.

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 two short, information-dense sentences. The most important behavioral cues—return value and 'call this first'—are front-loaded, and every clause adds value.

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 identity/auth check tool, the description is complete: it names the return payload, explains the non-destructive nature, and gives clear invocation guidance. No output schema is necessary given the simple return value described.

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 has zero parameters, so there is no parameter meaning to clarify. The description appropriately focuses on return value and usage context instead, making the schema's empty properties object fully sufficient.

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 exactly what the tool does: 'Returns key name + workspace.' It is clearly distinguished from all sibling tools, which are CRUD/data operations rather than an authentication identity check. The title 'Verify your API key' reinforces the purpose.

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

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

The description explicitly says 'Call this first,' giving a direct usage directive. It also labels itself as a non-destructive auth check, which makes it obvious that this is a safe preliminary step before mutation tools. Given the sibling list is all write/read operations with no other auth tool, no alternative comparison is needed.

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