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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful contextual behavior like the committee_id requirement for itemized mode and the candidate_id fallback for some aggregate modes, but it does not go deeper into pagination behavior, cursor constraints, or sorting quirks that are left to the schema.

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 two sentences, front-loads the primary function, then adds the use case and the essential mode/ID constraints. Every sentence earns its place with no filler or redundant restatement of the tool name.

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?

Given 19 parameters, a rich schema, an output schema, and read-only annotations, the description covers the key selection and invocation context: what the tool returns, who should use it, and the central committee_id/candidate_id distinction. It does not mention by_employer/by_occupation ID requirements explicitly, but the schema fills that gap.

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 description coverage is 100%, so the schema itself documents all 19 parameters thoroughly. The description adds one meaningful cross-parameter constraint (itemized requires committee_id; by_size/by_state can use candidate_id), but since candidate_id's schema description already says it "Enables by_size and by_state aggregates without a committee_id," the added semantic value is modest and stays at the 3 baseline.

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 itemized individual contributions (Schedule A) or get aggregate breakdowns by size, state, employer, or occupation." It also names the core question the tool answers, "who is funding this committee?", and clearly distinguishes incoming contributions from sibling outgoing-money tools like search_disbursements and search_expenditures.

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 a clear use case ("who is funding this committee?") and an explicit mode constraint: "Itemized mode requires a committee_id." It also notes that "Aggregate by_size/by_state can use candidate_id instead." However, it does not explicitly name alternatives or state when not to use this tool, such as directing spending-related questions to search_disbursements.

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