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

Annotations only declare basic traits (not read-only, open-world, not idempotent, not destructive). The description adds substantial behavioral context beyond that: the free-tier cap of 3 active alerts per origin, the two auth modes (Bearer key or api_key param), per-category check frequency (inmag=daily, rest weekly), threshold units (ARS/kg live), and the return value. No contradiction with annotations; readOnlyHint=false aligns with 'Crea'.

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?

Three dense sentences with zero waste: core function front-loaded, then the write-vs-read positioning, then pricing/auth, then a compact param summary, then return value. Despite covering 6 params, auth, rate limits, and delivery modes, every clause earns its place.

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 write tool with 6 params, dual delivery channels, tiered auth, and no output schema, the description is remarkably complete: it covers purpose, trigger behavior, limits, auth, param semantics, and the return value (id, precio), compensating for the missing output schema. Only minor gaps remain — the webhook POST payload shape and alert lifecycle management are not described.

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 high (83%), so the description doesn't need to re-document parameters, but it adds real value beyond the schema: the ARS/kg vivo unit for umbral, the frequency semantics per categoria, the above|below default, and the 'at least one of email/webhook_url' constraint that the schema does not encode in its required list.

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 opens with a specific verb and resource ('Crea una alerta'), defines the trigger condition (price crossing a threshold), and names the delivery channel (email/webhook). It also explicitly differentiates from siblings with 'Única tool de escritura (el resto lee)', making it unmistakable among 22 read-only tools.

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?

The description explicitly positions the tool against alternatives: it is the only write tool while all others read, so the agent knows when to pick it. It also gives concrete routing guidance within the tool — email for a person, webhook for integrations — and states the free-tier versus Enterprise-key conditions for invoking it. No inference is required.

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