create_aviso_from_photo

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

With no annotations, the description carries the full behavioral burden and does well: it discloses the four-phase state machine, that phase 3 produces a preview without sending, and the hard gate that all three of confirm/human_confirmed/preview_token are required or nothing is sent. It does not cover auth requirements, rate limits, or error behavior.

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 purpose is front-loaded in the first clause, followed by the preferred path, then the phases in order. It is telegraphic and dense but every sentence carries workflow information, appropriate for a 21-param multi-phase tool with no waste.

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 complex stateful tool with 21 params, no annotations, and no output schema, the description covers the workflow and the per-phase outcomes (need_category, need_street, preview_token) that an agent needs to drive the loop. Gaps remain around the peripheral geographic/identity fields, but the call-critical path is complete.

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 only 57% across 21 params, but the description compensates by explaining the operational meaning of the key gate fields: service_code missing returns suggestions instead of creating, confirm=true actually sends, and human_confirmed means a human approved the preview. Several fields (x, y, kind, portal, allCity, portalBis, districtCode, streetCode, neighbourhoodCode) remain undocumented in both places.

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 names a specific verb and resource ('Aviso desde una FOTO en fases') and makes the photo-driven, phased nature explicit, which distinguishes it from the plain create_aviso sibling. It does not name create_aviso directly as the non-photo alternative, so the differentiation is implied rather than stated.

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?

It gives concrete when-to-use routing per phase (no service_code → suggest categories; no street → ask for street; confirm=false → preview; confirm=true → send) and states the preferred upload path (PUT /upload + file_id in remote, image_path under stdio). It lacks an explicit 'do not use this when...' clause or a pointer to create_aviso for non-photo cases.

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