ava_artifact

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

Goes well beyond the annotations: it discloses that two files are written (HTML plus evidence JSON) and must not pre-exist, that invalid bindings error out before any files are created, that truncated results are skipped and surfaced in chartErrors while tables/SQL remain, and that sharing the HTML shares its query results. It also honestly scopes what it does not do (no independent verification of conclusions or browser rendering).

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 and the pre-call binding requirement, and nearly every sentence carries a distinct constraint or failure mode. The prose is telegraphic and dense, reading as a checklist rather than structured paragraphs, which slightly hurts scanability but wastes little.

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 multi-section report builder with no output schema, it covers the write side effects, the error/retry path, the return values (output and dataOutput), and the evidence file contents. Array caps (16 sections, 6 metrics) and the metrics structure are left entirely to the schema, but nothing an agent needs to make a valid first call is absent.

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 71%, and the description adds the crucial meaning the schema only implies: chartFields must sit beside chart at section level, mapping native field to exact query column, plus a complete worked section example and the distinction from chartConfigField. It leaves metrics, definitions and limitations to the schema, which is reasonable given their inline descriptions.

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 gives a specific verb and resource — 'Create a report from existing queryIds' — and ties the input to the ava_query sibling, so an agent can tell this assembles a deliverable rather than running SQL. It does not explicitly contrast itself with ava_viz, so the boundary with the visualization sibling must be inferred from the chart/section vocabulary.

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?

Strong procedural guidance: inspect results first, bind columns via chartFields, use chartConfigField for histogram/dual-axes/liquid, reuse the queryId instead of rerunning SQL, and fix bindings and retry the same output path on error. What's missing is an explicit statement of when to prefer a sibling (e.g. ava_viz for a single chart) over building a full report.

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