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

Beyond the readOnly/openWorld annotations, it discloses the default window (last year, weekly/monthly buckets), what population is counted (current roles only unless include_past_roles), that shares are of scored lines with short lines excluded, and that `low_sample` flags fewer than 20 underlying lines. Those sampling caveats are exactly the kind of trait an agent needs to interpret the numbers honestly.

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 purpose and example queries are front-loaded, and the two follow-up paragraphs cover population and caveats rather than restating the name. It is dense and long for a tool description — the examples paragraph could be trimmed — but nearly every sentence carries usable information.

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 7-parameter analytical tool with no output schema, the description explains what the payload contains (shares per bucket per interval, speaker counts, low_sample flags) and how to enrich it with examples. It stops short of describing the response's structural shape, but the default markdown rendering and schema docs cover most of 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 coverage is 100%, so the baseline is 3; the description adds real meaning on top by explaining that include=['examples'] returns a strongest line per bucket with a `person_slug` usable in the person sibling, plus an episode and a playable link. It also clarifies the population semantics tied to include_past_roles, though it doesn't touch interval or output_format beyond what the schema already says.

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 framing — 'how a company's people speak on podcasts' broken into negativity, hedging, vagueness, and time orientation — and immediately names the exact metrics returned. It distinguishes itself sharply from the sibling `particle_person_get_statement_characteristics` by scoping to a whole company's people rather than one person.

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?

It gives concrete trigger questions ('how confident do OpenAI's people sound lately', 'are Microsoft's executives talking more about the future'), names the single-person alternative, and states the prerequisite of resolving the company first with `particle_company_resolve`. Both the when-to-use and the when-not-to-use path are explicit.

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