a11y_contrast_image

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

The description discloses the method ('muestrea píxel a píxel' — samples pixel by pixel) and the output metrics (ratio worst/median/p95 and % area passing AA). Since no annotations are provided, the description carries the full burden, and it does convey meaningful behavioral traits beyond a mere 'checks contrast.' It does not mention performance or side effects, but for a read-only analysis tool this is acceptable, and the heavy-sampling note hints at computational cost.

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, dense sentence that front-loads the purpose, then lists outputs, and ends with the region hint. Every clause adds meaning, with no filler or repetition. It is 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?

Given there are 5 parameters, no output schema, and no annotations, the description is incomplete. It omits the meaning of 'sample' and 'lang', does not state the format for 'text_color' (e.g., hex/rgba) or 'path', and does not describe the return structure beyond the metrics. While it gives a region syntax example, it lacks enough detail for a fully autonomous agent to invoke the tool correctly without additional assumptions.

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 0%, so the description must explain the parameters. It covers only 'region' (with syntax and recommendation), while 'sample', 'lang', and the exact format of 'path' and 'text_color' are left undefined. The description adds some value for region but fails to clarify the others, leaving an agent to guess about the number of samples or language options.

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: 'Contraste de TEXTO SOBRE IMAGEN' (text-over-image contrast). It specifies the action (sampling pixel-by-pixel), the resource (image background), and the outputs (worst/median/p95 ratio, % area passing AA). This distinguishes it from siblings like a11y_contrast_pair (which likely works on solid colors) and a11y_audit_url (which audits a URL).

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?

Usage guidance is implied by the phrase 'TEXTO SOBRE IMAGEN' — it should be used when checking contrast of text over an image background, not solid colors. However, it does not explicitly mention alternatives or when-not-to-use conditions. The only explicit guidance is the recommendation for the 'region' parameter, which is parameter-level advice rather than tool-selection guidance.

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