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

Annotation coverage is thin (readOnlyHint=false, openWorldHint=true), and the description carries the behavioral burden: per-call duration (about 25 seconds), that up to 5 dossiers are returned per call, the response shape (batch_id, status, what is left), and billing (20 credits per new post, 2 per post read in the last 6 hours). It also discloses that an existing open batch is reused rather than a new one created, which is non-obvious and affects correctness.

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 information is front-loaded with scope first, then the polling loop, then billing, and nearly every sentence is operational. It is dense to the point of being long-winded in places (the no_credits and cancel sentences could be tightened), but 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?

This is a stateful, multi-call batch tool with no output schema, so the description must explain the return contract, and it does: dossier format matching read_post, no images, batch_id, status, remaining work. Combined with the cost and cancellation rules, an agent has everything needed to drive the batch to completion.

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, but the description adds real meaning beyond it: urls is first-call-only, batch_id substitutes for urls on continuation, and cancel is only meaningful combined with batch_id ('call with batch_id and cancel true'). Those sequencing constraints are not derivable from the flat schema, which marks nothing as required.

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 opening sentence pairs a specific verb with a concrete resource and quantity ('Reads 1 to 50 posts at once') and explicitly scopes the use case to comparing several posts, a profile, or a campaign. It also names the sibling read_post as the single-post equivalent and distinguishes itself from it, so an agent can route without opening either schema.

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?

The description gives explicit when-to-use and when-not-to-use rules: poll again with only the batch_id when the response asks for it, do not resend links, and do not fall back to read_post for missing ones. It also covers the decisions an agent may have to make: top up on no_credits, cancel to abandon a batch, and that repeat or unknown links cost nothing.

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