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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds material behavior an agent could not infer: full-length descriptions exceed the output cap and the call fails outright rather than truncating, the page caps at 200, and offset paging never skips or repeats because the sort is total. It also explains count semantics — total_matching is a count of everything the filter matched, not the page size.

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?

Front-loaded with what the tool returns, then the two highest-stakes directives (the unjudged query, and brief as default) before the paging caution. The all-caps emphasis is justified by a real failure mode (call fails outright), and no sentence is filler.

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 8 optional params and no output schema, the description does the heavy lifting: it names the two response fields that matter (total_matching, has_more) and warns that a page is not an answer to 'how many'. It stops short of describing row fields or the actual sort order, which leaves a small gap for a listing tool this configurable.

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 baseline is 3, but the description adds genuine meaning: judged=false is not equivalent to any verdict filter because an unjudged row has no verdict at all, and brief interacts with limit (lower the limit when using brief=false). It does not add anything for offset, company, source_id, or promoted beyond the schema.

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 first sentence states the resource precisely — 'one page of staged rows, with an honest count of everything the filter matched' — which tells an agent it is a paged, filtered list rather than a single-record fetch or a mutation. It does not name the sibling that would be used instead (e.g. pros_sources for pulls, pros_qualify for judging), so the differentiation is implied rather than explicit.

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?

Gives concrete when-to-use direction: 'judged=false IS THE "WHAT IS LEFT TO JUDGE" QUERY and it is usually the one you want', plus 'ask for brief=false on the handful where the cut description genuinely is not enough, and lower the limit when you do.' That is real operational guidance, but it never routes to or excludes an alternative sibling tool by name.

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