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

Annotations only declare readOnlyHint; the description adds substantial behavior on top: deduplicated person counting, the fact that `removed` overlaps the stage keys and stays at the stage reached, the special definition of Accepted (connection requests the campaign sent), the 15-minute freshness of covering groups' tagging, the thin/early/solid thresholds on `contacted`, and what out_of_credits means. It also warns not to divide counts but to quote the provided percents.

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 is front-loaded and the summary/returns separation is clean, but the prose is dense and occasionally jargon-laden ('the numbers on the Summary's rungs', nested relative clauses), which slows parsing. Nearly every sentence carries real information, so the length is largely earned rather than padded.

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?

There is no output schema, so the embedded returns block has to carry the full burden — and it does, enumerating groups/selected/funnel keys, rate vs. step_rate semantics, null conditions for `targets`, the 'No match' entry, multi-tag double counting, and not_tagged/out_of_credits. Nothing an agent needs to interpret or call the tool is missing.

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?

With 100% schema description coverage, the schema already documents agent_id, group_id (including the 'first group that tags this campaign' default) and on_behalf_of, so baseline is 3. The description adds indirect value by pointing at `selected.group_id` and `groups` as the source of valid group ids, but it does not extend the meaning of any parameter 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?

Opens with a specific verb and resource: 'One campaign's lead funnel split by a segment group's tags', and immediately distinguishes itself from the sibling get_segment_rates by explaining the counting difference (each person once vs. each channel separately). An agent can route between the two 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?

Gives explicit usage framing ('how are VPs doing on this campaign', 'which seniority replies best here'), an explicit alternative (get_segment_rates) and the condition that selects it, plus a concrete drill-down path: call list_people with agent_id, segment_group_id, a 'segment' tag filter and a 'reached' rung filter. It even states a negative case: 'No filter lists Accepted's people.'

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