a11y_suggest_color

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

Sin anotaciones, la descripción carga con todo el peso y aporta datos genuinos: desvela que la búsqueda es de mínima distancia a fg y fija el valor por defecto del ratio en 4.5 (estándar AA para texto normal). Esto es información que ni el nombre ni el esquema ofrecen. Para una función pura el listón es más bajo (no hay efectos laterales que advertir), pero hay vacíos que pesan: no se dice quién gana si ya se cumple el ratio, el espacio de color de la distancia, el formato de retorno del color sugerido, ni los límites del parámetro 'target'. Con cobertura de esquema al 0% y sin anotaciones, un contrato de retorno habría redondeado el comportamiento.

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?

Una sola frase densa en información con cero desperdicio. Ordena perfectamente los elementos: el criterio de proximidad ('más cercano a fg'), la condición ('que alcance el ratio objetivo'), la referencia ('contra bg') y la regla de defecto (4.5). Cada palabra aporta valor y el defecto aparece al final, donde debe estar.

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?

Aunque no hay esquema de salida, la descripción sí que cubre el contrato de retorno de forma implícita: 'color más cercano a fg' es la especificación del valor devuelto, y además fija el defecto. Para una función pura con tres parámetros planos y sin enums ni objetos anidados, el barrido de escenarios sobre los que comunicar es bajo y la cobertura es suficiente. Los únicos vacíos reales que evitan el 5 son la serialización de la salida y el comportamiento en casos límite (por ejemplo, si fg ya cumple el ratio o si target no es alcanzable).

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?

Con 0% de cobertura en el esquema, la descripción es la única fuente semántica y compensa en parte: aclara que fg es el color de referencia a aproximar, bg es el fondo contra el que se mide el contraste y target es el ratio con defecto 4.5. Aun así, no hay ningún detalle de formato: ¿cómo se serializan los colores (hex, rgb, nombres CSS)? ¿Qué rango admite target? Al ser la descripción la única vía para entender los parámetros, la ausencia de formato deja lagunas que el agente deberá asumir.

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?

La descripción es técnicamente precisa: expresa el verbo implícito ('sugerir'), el recurso (un color) y la restricción exacta que define la operación (el color más cercano a fg que alcance el ratio contra bg, con defecto 4.5). Comunica claramente una función de optimización de contraste, no una simple verificación. Sin embargo, le falta un verbo explícito y no diferencia a propósito de hermanos como a11y_contrast_pair o a11y_contrast_image, que es exactamente donde necesita orientar al agente.

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?

El contexto de uso se infiere de la claridad del propósito: un agente que necesite un color que cumpla el contraste contra un fondo sabrá que esta es la herramienta. La función se describe de forma tan específica que el caso de uso está implícito. No obstante, no hay ninguna orientación sobre cuándo NO usarla o qué alternativas existirían. Dado un conjunto de 8 herramientas hermanas en el dominio de accesibilidad con solapamiento real (contrast_pair, contrast_image), el silencio sobre alternativas es un vacío que evita el 4.

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