Charts by Szum

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

The description adds meaningful behavioral context beyond the annotations: it states that deletion cannot be undone, that retrying succeeds (idempotency), and that authentication is required. These are important operational details not present in the structured 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 a single, compact sentence that front-loads the usage context and packs in essential behavioral notes (permanence, idempotency, auth). Every clause earns its place; there is no redundancy or 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 delete operation, the description covers all necessary contextual aspects: when to use, permanence, idempotent retry, and authentication. An output schema exists, so return values are covered externally. The tool is fully specified for an agent to select and invoke 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 already fully documents the single 'id' parameter with a clear description and pattern. The tool description does not add additional parameter semantics, but since schema coverage is 100%, a baseline score 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 clearly specifies the action ('permanently delete') and the resource ('one saved chart'), which distinguishes it from sibling tools like rename_chart, update_chart, and get_chart. The explicit mention of 'permanently' adds important specificity.

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 a clear when-to-use directive: 'Use this when the user explicitly wants to permanently delete one saved chart.' It does not explicitly mention when not to use it or name alternatives, but the context is clear and the idempotency note ('retrying an already completed deletion succeeds') provides additional usage nuance.

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 adds important behaviors beyond annotations: displays published chart when available, does not return config, and requires authentication. No contradictions 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?

Two sentences, front-loaded with usage trigger, and no wasted words. Every sentence 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?

Given the presence of an output schema, the description needn't detail return values. It covers purpose, usage, and behavioral traits completely for a simple 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% with a detailed description of the 'id' parameter. The description adds no additional meaning beyond referring to 'by id', so baseline score 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 clearly states the tool retrieves chart metadata and URLs and displays the published chart. It distinguishes from sibling get_chart_config by explicitly noting that it does not return the config.

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 states when to use ('when the user identifies a saved chart by id') and provides exclusions ('does not return its config'), guiding the agent to use get_chart_config 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?

The description adds meaningful behavioral context beyond the readOnlyHint and destructiveHint annotations: it states the returned config is the 'published' version, not a newer editor draft, and that authentication is required. These are non-obvious traits that help the agent set correct expectations.

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 long, front-loaded with the primary use case, and contains zero redundant or filler text. Every clause adds value, making it concise and well-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?

For a single-parameter read-only tool with a full parameter description, output schema, and annotations, the description covers the essential usage context: when to use, what it returns (published config), key caveat (no editor draft), and authentication requirement. It is complete and self-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?

Schema description coverage is 100% for the only parameter 'id', which already describes it as an opaque 32-character saved-chart id. The tool description merely restates the parameter's role ('by id') without adding new format or usage details, so the schema carries the semantic load. Baseline 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 clearly states a specific verb ('get') and resource ('chart config'), and differentiates from the sibling 'get_chart' by specifying 'complete published Szum config' and 'inspection or reuse'. This is a precise, unambiguous purpose statement.

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 tells the agent when to use this tool ('when the user identifies a saved chart by id and needs its complete published Szum config'), and also provides an exclusion ('Does not return a newer editor draft') and a precondition ('requires authentication'). This is strong usage guidance with clear 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 indicate a safe read operation (readOnlyHint=true, destructiveHint=false). The description adds useful context by explaining that results are current, ready-to-use configs and preferred semantic patterns, and that filtering is optional. 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 two sentences, front-loaded with the primary use case, and contains no redundant or filler content. Every phrase contributes to understanding how and when to use the 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?

The tool is simple with one optional parameter, an output schema is present, and annotations cover safety. The description covers purpose, usage context, and filtering capability, making it fully adequate for selection and 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 description coverage is 100%, and the single parameter 'mark_type' is already documented as 'Filter examples by mark type' with an enum. The description merely repeats this as 'Optionally filters examples by mark type', adding no new 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?

The description clearly states the tool provides 'current, ready-to-use Szum chart configs or preferred semantic patterns' and optionally filters by mark type. This distinguishes it from sibling tools like get_chart or get_chart_config, which fetch specific charts/configs rather than example patterns.

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 explicit guidance on when to use the tool ('Use this when the model needs current, ready-to-use Szum chart configs or preferred semantic patterns'). It does not mention exclusions or alternative tools, but the context is clear enough for selection among 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 already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond annotations: it is 'owner-scoped when authenticated' (access control) and 'hidden from the model' (visibility). No contradictions.

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, front-loaded with the core use case and followed by behavioral traits. Every sentence is meaningful with no 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 single parameter, rich annotations, and existence of an output schema, the description fully covers context: when to use, behavioral aspects (read-only, scoping, visibility), and the parameter is well-described in the schema. No gaps remain for effective tool selection and 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 100% with a clear description for previewId (opaque 16-character id). The tool description does not add any additional parameter-specific meaning, so the 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 clearly states the tool's purpose: to restore a rendered preview as the current view. It uses specific verbs ('restore') and distinguishes this preview-specific tool from sibling chart manipulation tools like get_chart or list_charts.

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 specifies when to use this tool: 'when the Szum chart App needs to restore a rendered preview'. It provides clear context but does not explicitly mention when not to use it or list alternatives, though siblings make the distinction obvious.

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 the readOnlyHint annotation, the description adds critical behavioral details: requires authentication, returns paginated metadata (not configs), and explains draft-only chart properties (publishedAt null, hasDraft true, sizeBytes 0). No contradictions 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 two sentences with no redundant information. It front-loads the purpose and then provides essential behavioral details, achieving high conciseness.

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 output schema exists and parameters are well-documented in the schema, the description adequately covers purpose, authentication, and special response field behavior. No gaps remain for effective tool selection.

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 does not add parameter-specific meaning beyond the schema's own descriptions; the behavioral details about drafts pertain to output fields, not input parameters.

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 lists charts from the user's saved library, distinguishes from siblings like get_chart and get_chart_config by noting it returns metadata and URLs not configs, 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?

The description explicitly says 'Use this when the user wants to find charts', providing clear context. However, it lacks explicit exclusions or alternatives to sibling tools, which prevents a higher score.

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 destructiveHint=false. The description adds that the tool returns properties and defaults, providing useful behavioral context beyond annotations. 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?

Two sentences, front-loaded with usage guidance, then return description. Every word earns its place; no waste.

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 that an output schema exists (not shown but indicated), the description does not need to detail return values. It covers when to use and what the tool returns, which is complete for a simple list tool with good annotations and 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?

The schema has 0 parameters, so schema coverage is 100%. The description does not need to explain parameters. Baseline 4 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?

The description uses a specific verb ('Returns') and resource ('mark types') and clearly distinguishes from sibling tools (none of which deal with mark types). It states both the use case and the output.

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 says 'Use this when choosing or configuring chart mark types', which tells the agent when to invoke it. No mention of when not to use or alternatives, but the context from siblings makes it sufficient.

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 and destructiveHint: false. Description adds that it returns every theme and guidance, consistent with read-only behavior. No contradictions.

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, front-loaded with usage context. Every word adds value; no 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?

Simple tool with no parameters and output schema present. Description covers purpose and return value sufficiently given the complexity.

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?

No parameters exist; schema coverage is 100%. Description adds no parameter details but isn't needed. Baseline 4 applies as description helps understand the tool's output.

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?

Description clearly states the tool lists themes for charts and provides guidance. It distinguishes itself from siblings like list_charts and list_marks by specifying the resource (themes) and context (for a chart).

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 says 'Use this when choosing a visual theme for a chart,' giving a clear when-to-use. No alternatives mentioned, but no sibling tool overlaps with this purpose.

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 indicate mutation (readOnlyHint=false) and not destructive (destructiveHint=false). Description adds that authentication is required and specifies what the tool does not change, providing valuable context beyond 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?

Single sentence front-loads purpose and scope. No unnecessary words; every part is informative. Excellent efficiency.

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 simplicity of the tool (2 params, clear boundaries), the description combined with schema and annotations is fully complete. Output schema exists, so return values are covered. No 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?

Schema already describes both parameters fully (100% coverage: id as opaque 32-char string, title as trimmed 200-char string). Description adds no additional parameter details, so baseline 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?

Description clearly states it renames a chart's library title without affecting config, state, or URLs. This verb-resource pair is specific and distinguishes from siblings like update_chart and delete_chart.

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 states when to use ('when the user wants to change a saved chart's library title'), what is not affected (config, publication state, URLs), and that authentication is required. This provides clear context for invocations.

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 annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description discloses validation logic, error/warning/suggestion handling, revalidation guidance, 1-hour preview retention, public URL behavior, and render allowance accounting. This is rich behavioral context that annotations alone do not 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 description is dense but every sentence contributes meaningful detail (usage, validation, handling, preview behavior). It is logically ordered from use case to action to results, 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 tool with an output schema, the description adequately covers the full lifecycle: when to use, validation requirements, error handling, preview specifics, and resource implications. No critical gaps are evident for the tool's complexity.

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 description coverage, both parameters (config and acknowledgeWarnings) are already fully documented in the schema. The description adds no param-specific meaning beyond what the schema provides, so the 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 clearly states the tool renders/previews charts and lists concrete outcomes (public image URLs, preview storage). It distinguishes itself from sibling tools like save_chart, update_chart, and validate_chart by focusing on preview/generation with validation.

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 says 'Use this when the user wants to preview or generate a chart' and explains the validation preflight benefit, giving clear context. However, it does not name alternative tools or provide explicit when-not-to-use conditions, 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.

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

Annotations only indicate a non-read, non-destructive operation (readOnlyHint=false, destructiveHint=false). The description adds critical context: idempotency key requirements, validation preflight behavior, warning/suggestion handling, authentication and storage needs, and the exact return links. This goes well beyond what annotations convey.

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 moderately long (8 sentences) but every sentence adds value—purpose, validation rules, idempotency, return values. It is front-loaded with the primary purpose. Slightly dense but not wasteful, earning a 4 rather than a 5.

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 an output schema and full parameter descriptions, the description covers all necessary usage context: when to use, validation workflow, idempotency, warnings, and return types. No gaps identified; it is complete for an AI agent to invoke 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 coverage is 100% and the config parameter description is already very detailed. The description itself does not add new parameter semantics beyond what the schema provides; it merely reiterates idempotencyKey and acknowledgeWarnings within the workflow. Per the baseline rule for high schema coverage, a score 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 action: 'permanently save and publish a chart from a Szum config.' This clearly distinguishes it from siblings like render_chart (temporary preview), validate_chart (check only), and update_chart (modify existing). The verb 'save and publish' is specific and 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 states when to use ('when the user wants to permanently save and publish a chart') and provides detailed validation workflow (revalidate only changed configs, errors block, warnings require approval, suggestions do not). However, it does not explicitly name alternative tools or state when NOT to use it, such as 'use update_chart for modifying an existing chart.'

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 richly discloses behavioral details beyond the annotations: validation once per generated/changed config, no revalidation of unchanged input, error/warning/suggestion handling, explicit user approval for warnings, revalidation before repair, refusal of unpublished changes, and auth/storage requirements. This exceeds the basic 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 dense but every sentence contributes specific guidance. It is front-loaded with the main purpose, then provides behavioral rules. A bit long but not wasteful.

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 complexity and the presence of an output schema, the description sufficiently covers the key behavioral aspects: validation rules, error handling, approval flow, refusal conditions, and auth. It doesn't describe return values, but the output schema handles that.

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 contextual meaning for acknowledgeWarnings by explaining that warnings require explicit user approval, which aligns with the parameter's purpose. It also clarifies the config should be the complete config, but overall the schema already covers 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 clearly states the tool's function: "replace and publish a saved chart's config while keeping its id and URLs." This is a specific verb+resource combination that distinguishes it from siblings like save_chart (which likely creates a new chart) and render_chart (which only renders).

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 says "Use this when the user wants to replace and publish a saved chart's config..." which gives clear usage context. It also mentions refusal conditions (unpublished editor changes) that implicitly define when NOT to use it, though it doesn't name alternative tools explicitly.

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 read-only and non-destructive, but the description adds crucial behavior: error/warning/suggestion outcomes, the preflighting behavior after a successful render, and the need to replace config with suggestedConfig and revalidate. This goes well beyond the basic 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 information-dense but organized logically, starting with usage, then workflow details, then characteristics. Slightly long but every sentence earns its place; could benefit from bullet points but remains efficient for the complexity.

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 complexity and the presence of an output schema, the description covers all essential aspects: when to use, preflighting, error/warning/suggestion behavior, and repair steps. It is complete enough for an agent to select and invoke correctly without additional context.

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 schema itself provides a very detailed description of the 'config' parameter, covering validation rules and examples. The tool description adds no extra parameter-level meaning beyond mentioning suggestedConfig, so the high coverage 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 clearly states the tool validates chart configs before rendering, saving, or updating. It distinguishes itself from siblings like render_chart and save_chart by specifying the validation context and emphasizing it is read-only, free, and fast.

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 says 'Use this when a chart config will be rendered, saved, or updated' and provides rules like 'Do not revalidate unchanged input; a successful render preflights it for later saves or updates.' It also explains how to handle errors, warnings, and suggestions, and mentions the repair workflow with suggestedConfig.

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