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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, and the description adds genuinely new context: this read operation is issued as a POST with filters in the body, and it lists the response keys (draw, recordsTotal, recordsFiltered, data, meta, table_id, settings). The 'inferred from traffic, confirm results' caveat is a useful honesty signal. It stops short of describing page-size limits or what meta/settings contain.

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 opening sentence and return-key list are well front-loaded, but roughly half the text is a repetitive, truncated enumeration of identical per-column keys that adds bulk without adding meaning. It should have been summarized (e.g., 'columns[0..N] each with data/name/searchable/orderable/search[value|regex]') rather than dumped verbatim.

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?

Given the tool's complexity, the description does supply the route, the transport quirk (POST for a read), the response shape, and the traffic-inferred caveat. But for a tool whose title promises paging and sorting, it never explains how to page or sort, and the body key list is incomplete, so an agent would likely need trial and error to build a working request.

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?

The input schema is a generic body object that explicitly defers to the description ('Match the fields listed in the description'), so the description is the only source of parameter detail. It enumerates DataTables column keys, but the list is a raw truncated dump (stopping mid-way at columns[6][searchable]) that omits the keys actually needed for the advertised paging and sorting (start, length, order[i][column], order[i][dir]) and explains none of the keys' meaning.

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?

States a specific verb and resource ('Search invoices') and adds the mechanism ('server-side table query: paging, sorting, filters') plus the underlying route POST /invoices/invoices_datatable. It does not distinguish itself from the near-identical siblings singleops_read_search_invoices and singleops_read_search_invoices_archived_invoices, so an agent cannot tell which invoice search to pick from the description 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 when-to-use or when-not-to-use guidance and no mention of the sibling invoice-search tools. The only caveat, 'Inferred from the SingleOps web app's own traffic; confirm results,' is a reliability warning rather than a selection rule.

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