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

Annotations already provide readOnlyHint=false and destructiveHint=false, so the tool is known to be a mutating create. The description adds valuable behavioral constraints: brand attribution is applied automatically and cannot be overridden; insight must cite verifiable numbers and hallucinated numbers return 422 with an anchor list. It also mentions the fallback path. While it doesn't cover rate limits or auth, the disclosures go well beyond the annotations and materially help the agent.

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 but dense with purpose. It front-loads the core purpose and preferred status, then adds constraints (brand attribution, insight validation) and ends with fallback and guidance. Every sentence adds value; however, the length and nested parameter description could be slightly streamlined without loss. It remains well-structured and readable for an agent.

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 nested objects and five parameters, the description covers required and optional fields, validation rules, fallback, and error behavior (422). It appropriately points to chart_instructions() for full spec reference rather than duplicating it. The absence of an output schema means return values don't need explanation. Minor gaps: it doesn't explicitly state whether the chart is immediately visible or if additional steps are needed, but the fallback reference and instruction pointer cover most needs.

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 goes far beyond: it specifies the exact title format with required year range and unit (with conditional rules based on get_dataset_info), requires insight to use only numbers from query results, and details the required and optional fields within the nested builder_spec object. This is a substantial addition that compensates for the complexity of nested parameters and clarifies usage 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 states a specific verb (create), resource (chart), and input (Builder spec) and clearly distinguishes itself from the sibling publish_chart by positioning itself as the preferred path with a defined fallback. It also names the tool it is not (publish_chart) and the condition that selects it, making the purpose unambiguous 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 states when to use this tool ('PREFERRED chart-creation path') and when not to (advanced use cases fall back to publish_chart). It also directs the agent to call chart_instructions() if unsure of the spec shape, giving clear context and exclusions. This is model guidance for selecting among siblings.

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