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

With no annotations, the description must carry the behavioral burden: it does disclose that this is a GET (safe read), that the response is "Fixed JSON", that a company must be explicitly supplied, and that query parameters are flat passthrough fields. It says nothing about pagination, result limits, default ordering, or error behavior, which matters for a list endpoint.

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 short fragments with no filler, and the most important constraint (explicit company required) is placed early. The telegraphic style is dense but every fragment carries information; only the endpoint path borders on redundant with the tool name.

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?

The output schema covers return values, and the pointer to describe_nextesy_operation covers filter enumeration. What is missing for a list tool is pagination/result-cap behavior and ordering defaults, which an agent needs to call it safely without assuming it returns everything.

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 0%, so the description must compensate for both parameters. "Explicit company required" clarifies that company_name is a mandatory tenant selector rather than a filter, and "Flat query fields" clarifies that query is an untyped flat object of passthrough filters — useful, but the actual filter keys are deferred entirely to describe_nextesy_operation.

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 identifies the operation via its HTTP endpoint ("GET /api/v1/sales/orders"), which does imply listing sales orders, but it never states the purpose in plain language ("list sales orders for a company"). It also does not distinguish this list operation from the sibling get_sales_order, leaving the agent to infer the singular/plural split from the names alone.

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?

"Explicit company required" gives one precondition, and "see describe_nextesy_operation for filters" correctly routes the agent to a sibling for filter discovery. However, there is no statement of when to use this versus get_sales_order or other list tools, and no exclusions or scope limits are given.

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