Descartar

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

Annotations already declare non-destructive, idempotent, closed-world behavior, so the bar is lower; the description nevertheless adds real consequence beyond them — discarded items are hidden from searches and deadline alerts, and the motivo is persisted to tune watchlists later. It does not say whether discarding can be undone, which is the main remaining gap.

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 one-line purpose, then when-to-call, then effect, then argument semantics. Every block earns its place; the Args section is slightly redundant with the schema titles but adds semantic detail rather than repeating types.

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?

With an output schema present and annotations covering the safety profile, the description supplies what's missing: trigger condition, visibility effect, and parameter provenance. Only the reversibility/undo story and any relationship to mark_solicitada are 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 description coverage is 0%, so the description must carry the semantics, and it does: id is identified as the 'id' field from a search_convocatorias result, and motivo is explained as the user's own words about why it was discarded, plus its downstream use. Both parameters gain meaning not present in 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?

States a specific verb and resource ('Descarta una convocatoria') plus the scope of the effect ('para que no vuelva a aparecer'). It also ties the id back to sibling tool search_convocatorias, so an agent can distinguish this from get_convocatoria or mark_solicitada.

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?

Gives an explicit trigger condition: call it when the user says something doesn't interest them or doesn't apply. It also states the consequence (excluded from searches and deadline notices), which clarifies the intended context. It stops short of naming alternatives or a when-not case, so not a 5.

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