get_visual_schema

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

Without annotations, the description discloses the return shape (cards -> properties -> {type, enum, min, max}) and the scoping behavior (omit card for full schema). This provides useful behavioral context beyond just saying 'get'.

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 the core purpose, no fluff. The structure follows the scoping logic clearly.

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 2-param read tool with no output schema, the description covers the return structure and scoping options. It doesn't specify error behavior or invalid inputs, but that's not essential for this straightforward getter.

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 baseline is 3. The description adds minor value by explaining 'omit card' behavior and giving examples (legend, valueAxis, title), but the schema already covers parameter meaning sufficiently.

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?

Clearly states 'Get the formatting schema for one visualType' with a specific verb and resource. Distinguishes itself by referencing list_visual_properties and the optional card scoping, which differentiates it from sibling tools like list_visual_properties or get_visual_format.

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?

Description provides clear context: use this for a compact schema of a single visualType, with optional card scoping. It references list_visual_properties as a comparison point, but doesn't explicitly state when to prefer one over the other, so no exclusions are given.

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