compras_arp_unidades_item

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

Annotations already cover the read-only, open-world, idempotent, and non-destructive profile. The description adds useful behavior beyond that: it names the public Dados Abertos endpoint and discloses the 15-minute cache. It also clarifies that the returned units are potential rather than actual caronas.

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 short and front-loaded with the main purpose. There is slight redundancy between 'potenciais caronas' and 'unidades podem usar a ata como carona', but the endpoint and cache statements are tight and informative, so the structure remains efficient.

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 filtered list tool with a fully documented input schema, an output schema, and safety annotations, the description covers the purpose, the data source, the carona semantics, and cache behavior. Nothing needed to call or interpret the tool correctly is missing.

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 100%, so the schema already documents all five parameters, including pagination defaults, limits, and the distinction from numeroControlePncpAta. The tool description adds no parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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?

Opens with a concrete verb and resource: 'Lista UGs participantes (potenciais caronas) de um item da ARP.' This is reinforced by 'Determina quais unidades podem usar a ata como carona (adesão)', which clearly conveys what the tool does. The 'potenciais caronas' framing also helps distinguish it from the related actual-adhesion sibling compras_arp_adesoes_item.

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 clearly defines when to use the tool: to list the UGs that may use the ARP item as a carona/adhesion. It does not explicitly name alternatives or exclusions, but the intended context is unambiguous and the endpoint reference adds operational clarity.

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