Search jobs report (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 the description adds real context: it clarifies the read is issued as POST with filters in the body, warns that the shape was inferred from app traffic, and enumerates return keys. The 'confirm results' reliability caveat is a valuable disclosure beyond the annotations, though it stops short of error/pagination behavior.

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?

Purpose and endpoint are front-loaded well, but the exhaustive columns[N][...] key dump is repetitive bulk that could be summarized as 'per-column objects with data/name/searchable/orderable/search[value]/search[regex].' The verbosity dilutes the otherwise useful content.

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 compensates by listing the return keys (draw, recordsTotal, recordsFiltered, data, meta, table_id, settings) and the POST-with-body read pattern. For a read-only query tool this is nearly complete, only missing a note on paging defaults or error handling.

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 100%, so the baseline is 3. The description does add value by enumerating the expected DataTables body keys (draw, columns[n][data|name|searchable|orderable|search][value|regex]), which helps construct the free-form body — but the list is truncated mid-structure (stops at columns[6][searchable]) and doesn't explain value semantics.

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+resource (search jobs report) and adds scope (server-side table query with paging, sorting, filters), so the agent knows it's a DataTables-style query. It does not differentiate from look-alike siblings such as singleops_read_search_jobs or singleops_read_get_archived_jobs_report, leaving ambiguity about which report 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 explicit when-to-use guidance or reference to alternatives, despite many sibling report/search tools. The only usage-adjacent signal is the caveat 'Inferred from traffic; confirm results,' which tells the agent to verify output but not when this tool beats singleops_read_search_jobs.

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