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

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

Adds real context beyond the annotations: the underlying endpoint (POST /invoices/data_table), the fact that it is a read-only query sent as POST with filters in the body, the response keys (recordsTotal, recordsFiltered, data, etc.), and the caveat that the shape was inferred from web-app traffic and results should be confirmed. The annotations already cover safety/idempotency, so this is a solid supplement.

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 front-loads well, but the bulk of the description is a machine-dumped, repetitive enumeration of nearly identical column keys that is truncated mid-item. It is noise rather than usable instruction, and a summary like 'DataTables request with per-column search/order config' would convey the same thing in one line.

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?

Covers endpoint, method, response keys and a reliability caveat, which is respectable for a tool with no output schema. But for a nested, free-form body parameter it leaves the agent without enough to construct a working request — valid column identifiers, filter value formats, and paging mechanics are all unstated.

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 coverage is technically 100%, but the schema itself just says 'Match the fields listed in the description', so the description must carry the parameter burden. It dumps raw DataTables keys (draw, columns[n][data], columns[n][search][value], etc.), which lists names but never explains what values are valid, which column names exist, or what 'draw' means, and the list truncates at columns[6][searchable].

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 clear verb+resource ('Search invoices') plus the mechanism: server-side DataTables-style query with paging, sorting and filters. That is far more specific than the title alone. It does not, however, distinguish itself from near-identical siblings such as singleops_read_search_invoices_2 or singleops_read_list_client_invoices, so an agent cannot tell which one to pick.

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 guidance on when to use this tool versus the several other invoice search/list tools in the sibling set. The only usage-adjacent statement is 'Read-only query sent as POST (filters go in body)', which explains mechanics rather than selection criteria.

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