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

With annotations already declaring readOnlyHint and idempotentHint, the description's job is lighter, yet it adds substantial behavioral context: pagination differences (keyset vs page-based), rejection of certain parameters in by_candidate mode, the sorting quirk with negative amounts, the default-cycle behavior, and the explicit timeout risk for unscoped scans. This goes well beyond the structured fields and contains no contradictions.

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 description is front-loaded with a concise purpose statement, then delivers all critical usage details in a dense but organized paragraph. Every sentence earns its place—mode requirements, pagination, sorting, cycle defaults, and timeout warnings are all included without redundancy. It is long but information-dense, with no filler or repetition.

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?

For a 20-parameter tool with two modes and many constraints, this description is remarkably complete. It covers mode selection, required vs optional parameters, pagination behavior, sorting, cycle handling, and even failure modes (timeouts, rejections). With an output schema present, no return-value explanation is needed. An agent has everything required to call this tool correctly.

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?

Even though schema description coverage is 100%, the tool description adds significant meaning: it explains that by_candidate requires candidate_id or full race scope, that cursor is only valid for identical calls, that most_recent only applies to itemized, and that certain parameters are rejected in by_candidate. It also clarifies sorting semantics with a concrete example (ascending leads with negative rows). This is far more than the schema provides.

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 description opens with a specific verb and resource: 'Search independent expenditures (Schedule E) — outside spending supporting or opposing federal candidates.' It clearly distinguishes from siblings like coordinated expenditures by naming the filing type, and explains the two modes (itemized vs by_candidate) and their use cases. The purpose is unambiguous and does not rely on the tool name.

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 provides explicit guidance on when to use each mode, including the parameter requirements for by_candidate (candidate_id or full race scope) and the default-cycle behavior to avoid upstream timeouts. It does not explicitly name alternatives among sibling tools, but the resource (Schedule E) is specific enough that an agent can infer when this tool is appropriate. A clear 'use this for independent expenditures, not coordinated' would push it to 5.

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