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

Annotations already declare this as a safe read operation, but the description adds meaningful behavioral context: the order status code map (0 new through 1000 cancelled), the distinction between header and positions, and the explicit note that no PDF export is performed. These are details an agent would not get from annotations alone.

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 front-loaded with the core action and filters, then adds the return shape and status codes in a compact form. The status enumeration is dense but useful; no sentence is merely filler, though the response-shape sentence could be tightened slightly.

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 no output schema, the description does the important work of explaining that results include a header (address, dates, payment terms, status) and positions. Combined with annotations covering the safety profile and the schema covering pagination parameters, this is nearly complete, though it could briefly mention that empty results are normal or how status codes relate to filtering.

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 already 100%, so every parameter is documented in the schema. The description restates the filter categories in prose (order number, customer, date range, customer's purchase order number) but does not add syntax, edge-case behavior, or filtering rules beyond what the schema provides; baseline 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?

The description gives a specific verb and resource ('Search Collmex customer orders') and identifies the underlying record type ('SALES_ORDER_GET'), which clearly separates it from siblings such as collmex_list_invoices and collmex_list_products. It also names the exact filter dimensions, so the agent knows precisely what is being searched.

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?

Usage is implied by 'customer orders' and by the explicit 'Reads only; no PDF export' limitation, but the description never names a sibling alternative or says when to choose this tool over collmex_list_invoices or collmex_list_open_items. It gives enough context to understand the tool's domain, but not explicit routing guidance.

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