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

Annotations already establish readOnly, idempotent, non-destructive behavior, so the description does not need to restate that. It adds valuable behavioral context: it returns raw Cakto data with pagination fields and supports batched execution. No contradiction with annotations was found.

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 bullet structure is efficient and front-loaded, and nearly every line earns its place. The cryptic '[Flattened action: get]' line and the Portuguese/English mix are minor structural distractions, but the description remains compact and scannable.

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 12-parameter read tool with no output schema, the description is fairly complete: it covers the two actions, most filters, value formats, pagination, and bulk behavior. The missing 'account' parameter and lack of explicit routing to sibling tools keep it from being fully 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?

With schema description coverage at 0%, the description carries the full burden and succeeds: it documents 11 of 12 parameters, including allowed values for type, offer_type, status CSV format, date formats for paid_at_gte/paid_at_lt, page, order_id, and order_ids. Only 'account' is left undocumented. This substantially compensates for the empty 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?

The description clearly states the resource ('pedidos na Cakto') and the specific operations: list with filters and get one order by order_id. It does not, however, explicitly differentiate itself from the sibling 'cakto_orders_list', so an agent may still be unsure which list tool to prefer.

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 gives internal usage guidance: list for listing with filters, get for a single order requiring order_id, and bulk support via order_ids. It does not state when to use this tool vs alternatives like cakto_orders_list or cakto_orders_analytics, and the '[Flattened action: get]' note adds ambiguity about which action is actually active.

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