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

Annotations already cover the read-only/idempotent safety profile, and the description adds real behavioral context: it discloses the returned values_filtering + exclusions[] structure with why-filtered reasons, guarantees no silent red-line drops, and states that unknown outcomes yield coverage rather than a guessed rating. Some of this is opaque jargon ('never invents CE', 'ADR 0007 Proposed') that an agent may not decode, which keeps it short of a 5.

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 preferred parameter are front-loaded, which is good, but the prose is dense and includes internal references ('ADR 0007 Proposed') and unexplained domain shorthand ('CE') that do not earn their place for an external agent. Several clauses could be tightened without losing signal.

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, and the description does the right thing by describing the return envelope (values_filtering, exclusions[] with reasons, coverage on empty/unknown results). But with 11 optional parameters and no required ones, it never says what the tool does with no arguments, and several filter parameters remain semantically dark.

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 only 45%, so the description must compensate, and it partially does: it explains values_profile_id as the preferred binding that loads outcome_preference, red_lines, risk, tax, and geography. However tax, risk, limit, non_cash, budget_usd, and require_geography receive no meaning beyond their enum names, leaving half the parameters undocumented anywhere.

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?

States a specific resource outcome: 'Conviction-ranked orgs for one outcome family,' which tells an agent this is a personalized ranked recommendation rather than a plain listing. It is distinguishable in spirit from list_charities or search_orgs, but never names those siblings to sharpen the contrast.

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 says to pass values_profile_id (preferred) and/or outcome, which is parameter-level guidance rather than a when-to-use rule. There is no statement of when to choose compare_charities, list_charities, or allocate_portfolio instead, so the selection decision stays implicit.

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