Search invoices archived invoices (server-side table query: paging, sorting, filters)

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so safety is covered. The description adds two genuinely useful traits beyond that: the endpoint was inferred from observed web-app traffic ("confirm results") and the response carries DataTables envelope keys (draw, recordsTotal, recordsFiltered, data, meta, table_id, settings). It does not explain the semantics of those keys (e.g., that draw is an echo counter) or any limits on length/start.

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 first sentence is well-formed and front-loaded, but it is followed by a ~50-item comma-separated dump of parameter names that duplicates the input schema verbatim and consumes most of the text. That bulk earns nothing and buries the one genuinely novel sentence (the inferred-traffic caveat) in the middle.

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 50 optional, nested parameters and no output schema, the description should explain how to build a valid DataTables query (what draw/start/length do, sane defaults, which columns map to which invoice fields) and what the returned data rows look like. It instead lists key names and stops, leaving an agent unable to invoke this confidently beyond passing everything through.

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%, but each schema description is a tautology ("Query parameter \"draw\""), so the schema itself conveys little meaning. The description contributes only a coarse grouping (paging = draw/start/length, sorting = order, filters = search/columns) and then re-lists the raw parameter names without explaining any of them. Baseline 3 is appropriate given coverage, but no real semantic lift is added.

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 a scoped resource ("Search invoices archived invoices") and gives the backing endpoint GET /invoices/archived_invoices_data_table, so an agent can tell this targets archived invoices rather than active ones. It does not explicitly contrast with the many similar siblings (singleops_read_search_invoices, singleops_read_search_invoices_2, singleops_read_list_invoices_invoice_totals), leaving disambiguation to the name 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?

There is no statement of when to use this versus the sibling invoice-search tools, nor any prerequisite, exclusion, or typical scenario. The parenthetical about paging/sorting/filters describes capability, not usage guidance.

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