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

With no annotations, the description carries the behavioral burden and mostly succeeds: it discloses write side effects (files land in <out_dir>/diagrams/<name>/, including editable source), return payloads (PNG preview, paths, embed snippets, lint findings), and spec-rendering behaviors such as AUTO direction layout, auto-rotating container tints, and auto legends. It stops short of describing error/edge behavior or the exact effect of preview_only.

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?

Long, but every sentence earns its place. It front-loads the core purpose and return values, then organizes the DSL by family (architecture, chart, canvas, meta) with no repetition or 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 complex tool with nested spec families and no output schema, this description gives the agent everything needed to invoke it correctly: output behavior, file destinations, valid spec shapes, defaults, and a usage trigger for the meta block. No critical invocation detail 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%, but the schema's spec property is nearly a stub. The description adds enormous semantic value by enumerating every spec family, its fields, allowed values, defaults, and composition rules (e.g., canvas layers can embed full chart/architecture specs), going far beyond the structured 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 opening sentence names a concrete verb and resource: 'Render a VizCharter diagram from a spec and export it.' It is clear about what the tool does, but it does not explicitly contrast with siblings such as vizcharter_update or vizcharter_export, so an agent must infer the creation-vs-update/export boundary.

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 makes the primary use case obvious and even adds a targeted trigger for the meta footer ('use it when the user asks for authorship...'). However, it never states when not to use this tool or when a sibling (update, export, templates) would be the right choice, so the selection guidance is implied 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?

With no annotations provided, the description carries the full behavioral burden. It transparently discloses the operation is non-destructive ('without changing it') and describes the filesystem side effect ('new formats are added to the diagram's directory alongside existing exports'). This is solid but does not address potential edge behaviors like overwrite semantics or what happens on failure.

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 concise sentences with no filler. The core action is front-loaded, and the important side-effect note is included without bloating the description.

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

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

The description, alongside a fully documented schema, gives an agent enough to select and invoke this tool correctly. It lacks an output-schema note about return behavior, but for a file-export tool this is a minor omission, and the side-effect behavior is explicitly disclosed.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds a light connection to 'formats or scales' but does not need to elaborate further because the schema fully captures the parameter details.

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 uses a specific verb ('Re-export') and resource ('existing diagram (.vizc.json source)'), and clearly distinguishes this from creation or editing tools. It immediately tells an agent this is about converting an existing artifact into other formats, not creating or updating the diagram itself.

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 clearly states this is for an existing diagram and that it does not change the source, which implies it is for follow-up work after creation. It does not explicitly name sibling tools like vizcharter_create or vizcharter_update as alternatives, but the 'existing' qualifier and 'without changing it' provide strong contextual guidance.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the fuzzy-search mechanism, the supported cloud vendor packs, the return payload (registry ids, vendor category, aliases), and the intended use. It does not detail ordering, empty-result behavior, or case-sensitivity, but the core behavior is clearly conveyed.

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, front-loaded with the action and scope, followed by the return value explanation. Every clause is informative and there is 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?

For a simple two-parameter lookup with no output schema, the description covers the essential return structure (ids, category, aliases) and gives concrete examples. It is slightly light on result ordering and exact return shape, but it is complete enough for an agent to call and interpret the result.

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

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

Schema coverage is 100%, with both `query` and `limit` documented. The description adds context about fuzzy matching and output contents but does not add meaning to the parameters themselves, so it stays at the baseline for high schema 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 uses a specific verb ('Fuzzy-search') and a precise resource ('bundled official cloud icon packs — AWS, GCP, and Azure'), and it explains the output's purpose as node `icon` values. This clearly distinguishes it from the sibling creation, update, export, theme, and template 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 phrase 'to use as node `icon` values' provides a clear usage context, implying it should be called before creating or updating chart nodes that need icons. It does not explicitly list alternatives or exclusions, but the context is strong enough for an agent to decide when this tool is relevant.

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

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

No annotations are present, so the description carries the behavioral burden. It makes clear this is a read-only listing action by saying 'List', and adds useful behavioral context: the template computes layout/page size and layers can be added alongside. It does not document response shape details, but for a zero-parameter listing tool this is adequate.

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 front-loaded. The first sentence states the action and outcome; the second adds essential usage context with a concrete spec example. Every sentence contributes, with no redundant 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, no-output-schema listing tool, this is complete: it identifies what is returned, why it matters, and how to consume it inside the canvas spec family. An agent has enough information to invoke and apply the result 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 zero parameters, so there is nothing to document. Per the 0-parameter baseline, the description does not need to compensate for missing schema detail, and it already explains how the returned template/slot values fit into the canvas spec.

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 clear verb-resource pair: 'List the canvas poster templates with their slot schemas.' This distinguishes the resource from sibling tools like icons/themes/export, since it is specifically about canvas poster templates and their schema structure.

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

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

Provides a concrete usage context: the templates are meant to be used with spec family 'canvas' and shows the expected spec shape. It does not explicitly contrast with sibling tools or say when not to use it, so it falls just 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.

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that validation checks against 'the token schema including WCAG contrast expectations', which is a useful detail. However, it doesn't explicitly state that the tool is read-only (though 'list' and 'validate' imply non-mutating actions) or describe the return format of validation results. There is no mention of side effects, error behavior, or prerequisites beyond the default base theme.

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 a single, well-structured sentence that front-loads the primary purpose ('List built-in themes') and then clearly explains the alternative validation mode with a conditional. Every word earns its place — no fluff, no repetition.

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 tool's simplicity (2 optional parameters, no output schema), the description covers the core functionality well. However, it does not explain what the return value looks like for either mode (e.g., a list of theme names, a validation report). For a validation tool, agents would benefit from knowing whether results are a simple pass/fail or include detailed errors. The absence of any return-format guidance is a gap, but the tool is straightforward enough that this isn't severely limiting.

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 both parameters with descriptive text (base has a default, overrides is described as 'Theme overrides to validate'), so baseline is 3 given 100% schema coverage. The description adds a key semantic detail: validation includes 'WCAG contrast expectations', which is not in the schema. It also explicitly ties `overrides` to the validation mode, but doesn't add anything about `base` beyond what the schema states.

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 two specific actions (list and validate) on a specific resource (themes), and clearly distinguishes from siblings like vizcharter_create or vizcharter_export by focusing solely on themes. The conditional guidance for passing `overrides` makes the behavior 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 explicitly tells the agent when to use this tool: to list built-in themes or validate custom overrides. It also implies that validation is conditional on passing `overrides`. It doesn't explicitly say when not to use it, but the sibling tool names (create, update, export, icons, templates) make the domain separation clear, so an agent can infer this is the theme-specific 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?

With no annotations, the description carries the full behavioral burden and does so well: it specifies RFC 7386 merge-patch semantics (recursive object merge, null deletes, arrays replace), explains that replacement overrides patch, states that re-rendering and re-export happen to the same location, and lists the return value. This is transparent about side effects and semantics.

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 dense sentences with no filler. The core purpose is front-loaded, followed by patch semantics, then side effects and return value. Every sentence adds information.

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

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

The description covers the operation, patch/replace semantics, destination of re-exports, and return value. With no output schema or annotations, this is a solid amount of context, though it omits potential failure modes or error behavior when lint findings are produced.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by explaining how patch and replace behave and how they relate to each other. Format defaults are still only implied by the schema enum and not explicitly stated, but the added patch semantics justify a 4.

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 names the exact verb and resource ('Update an existing diagram from its .vizc.json source') and immediately distinguishes this from create/export siblings. The phrase 'existing diagram' plus the source file reference makes the tool's scope unmistakable.

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 clearly states this is for updating an existing diagram from its source file, which implies when to use it instead of create or export. However, it does not explicitly name alternative tools or state when not to use them, so it falls just short of full guidance.

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