Did It Work?

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds meaningful context beyond them: it names the return shape (gifts[], modeled_portfolio_impact) and discloses the provenance guarantee ('verified claims only — never invents CE') plus the caveat 'modeled≠guaranteed'.

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?

Two tight sentences, front-loaded with the verb and resource, then the return contract. Some compression is excessive ('never invents CE' is internal jargon an uninitiated agent may not resolve), but nothing is wasted.

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 9 parameters, low schema coverage, and no output schema, the description does supply the key output field names and a provenance caveat. However it leaves the effect of risk, tax, geography, include_funds and top_n unexplained, which is a real gap for an allocation tool.

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 only 33%, so the description must compensate, and it does not. It explains budget_usd and the method enum, but says nothing about tax, risk, geography, top_n, include_funds, or red_lines — all of which materially change the allocation an agent gets back.

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 verb and resource ('Suggest a donor portfolio: split budget_usd across top-ranked orgs') and enumerates the three allocation methods. It is clearly a multi-org allocation tool, distinguishable in spirit from single-org siblings like recommend_charity, though it never names those siblings explicitly.

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?

Usage is implied: this is the tool for splitting a budget across multiple orgs by method. But there is no explicit 'use this when X, use recommend_charity/compare_charities when Y', and no stated prerequisites (e.g. whether orgs must already be ranked, whether budget must exceed a minimum).

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

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

Goes well beyond the read-only/idempotent annotations: it discloses that no figure, rating or order is added, that cross-unit comparisons are flagged via units_differ.sentence because conversion requires a moral judgment, and that modeled figures carry guaranteed: false. These are exactly the behavioral caveats an agent needs before presenting results.

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?

Front-loads purpose then follows with caveats and output contract; every clause carries information. The decision_brief enumeration is dense but each item (donate_url, evaluator fund, comparison page, modeled flag) is distinct content, not padding.

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?

With no output schema, the description carries the return-value burden and does so (units_differ, decision_brief contents, modeled/guaranteed flags). Minor gaps remain around error behavior for unknown or duplicate ids, but nothing essential for correct invocation 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?

Schema coverage is 100% and the single parameter already documents comma-separated ids with a minimum of two. The description only reinforces the org_* id format and the count minimum, so baseline 3 applies.

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 verb and resource ('side-by-side claims, recommendation tiers, and trust for two or more org_* ids'). The multi-org scope and listed outputs distinguish it from single-entity siblings like get_org, get_trust, and list_charities without ambiguity.

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 'two or more org_* ids' constraint implies when the tool applies, and the units_differ note explains a comparison-specific situation. However, it never names an alternative (get_org for one charity, recommend_charity for a single pick) or states exclusions, so routing still requires inference.

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

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

Annotations already state readOnlyHint, idempotentHint, and non-destructive behavior, so the description's added value is in clarifying what does not happen: no payment processing, no card storage, no Stripe calls, donation_proof=null, and modeled impact is not guaranteed. That is meaningful behavioral context beyond annotations, though rates, side effects, and idempotency details are left to annotations.

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 short, front-loaded, and mostly dense with useful facts. Some phrasing such as 'Did It Work?' and 'Phase 3 MVP' is internal shorthand that slightly reduces clarity, but there is little waste.

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 5-parameter tool with no output schema, the description does describe the return shape and the no-charge handoff clearly. However, it omits most parameter semantics and provides weak usage guidance, so it is only minimally complete for correct invocation.

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 only 20%, so the description carries most of the parameter burden but explains only include_impact indirectly via 'Optional modeled_impact is modeled≠guaranteed.' It says nothing about org_id, amount_usd, vehicle enum, or values_profile_id, leaving most required inputs undocumented.

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 states a specific action and outcome: a no-charge deep-link giving handoff that returns mode=deep_link, donate_url, and charge=false. It is clearly distinct from sibling tools like allocate_portfolio or recommend_charity, though the 'Phase 3 MVP' phrasing adds noise rather than precision.

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 only usage guidance is 'Prefer GET; POST accepts the same fields as JSON body,' which is a transport note rather than when-to-use guidance. It does not say when an agent should choose this tool over alternatives or what prerequisites apply.

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

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

Goes well beyond the readOnly/idempotent annotations: it states the tool computes no new figure, gives no score, never ranks across causes, and fails closed on empty input, unknown arguments, injected instructions, unknown org or bad budget. It also discloses that dollar amounts in the question are re-read as budget and that modeled figures are not guaranteed. This is unusually rich behavioral disclosure.

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 first sentence is well front-loaded, but the body is a single enormous paragraph of changelog entries ('Since wave 52', 'wave 56', ... 'wave 69') that is version history rather than guidance an agent needs. Much of that text describes internal routing and spec-evolution detail that crowds out the actionable facts.

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?

With no output schema, the description does the heavy lifting by enumerating return fields (answer, kind, shortlist, give_url counts, quote, report_back) and the fixed answer keys. It is complete enough to call safely, though the dense, unstructured enumeration makes it hard to extract the return contract at a glance.

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 75%, and the description meaningfully extends it: org accepts id or slug, budget_usd only adds estimate_impact's modeled say_as sentences for a single named charity, and a dollar amount written in the question is parsed the same way when budget_usd is absent. The cause parameter, however, is only named as optional with no semantics added.

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 opening ('One call, one defensible answer') plus the input summary and return-field enumeration make it clear this is a question-answering/router tool that returns a structured brief. It even differentiates itself from search_orgs by noting it carries the same fixed answers. The core purpose is nonetheless buried under later wave-by-wave detail, so the agent must read far before confirming scope.

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?

Usage is implied rather than stated: the description enumerates what kinds of questions map to what internal 'kind' (fund_or_pick, figure_request, village_effects), which is routing behavior, not tool-selection guidance. There is no explicit 'use this instead of compare_charities/recommend_charity when...' statement, and no exclusion of siblings beyond the search_orgs overlap note.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important behavioral traits: it never invents CE, always marks results modeled:true and guaranteed:false, returns insufficient_data when no usable verified unit exists, rounds say_as while keeping exact arithmetic in expected_value, and never adds figures, ratings, or ordering. This is rich context that materially improves correct invocation.

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 dense but front-loaded with the core purpose and modeling guarantees. Some wording is repetitive (modeled:true / guaranteed:false appears twice), but every sentence contributes behavioral information rather than filler.

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?

With no output schema, the description carries the burden of explaining return structure, and it does so well: outcomes include say_as and expected_value, decision_brief includes donate_url, evaluator fund alternative, comparison page, and modeled/guaranteed flags. An agent has enough information to interpret and present results 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?

Schema coverage is 0%, so the description must compensate. It clarifies that gift_usd scales the modeled outcomes, which adds meaning beyond the schema, but it does not explain org_id or give format expectations for either parameter. The partial explanation justifies a 3 rather than a lower score.

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 states a specific action and resource: modeling expected outcomes from verified org claims scaled by gift_usd. This is distinguishable from sibling tools such as compare_charities or recommend_charity because it focuses on quantified impact estimation for a single org and gift amount.

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 implies when to use it (when an agent wants a modeled impact estimate for a gift) and gives a failure condition (insufficient_data), but it does not explicitly state when to prefer this over alternatives like compare_charities or recommend_charity. Guidance is present but implicit.

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

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

Annotations already declare readOnly/idempotent/closed-world, so the description's added value is the index-only, no-fabrication guarantee, the note that provenance metadata rides on the response, and the warning that org narrative fields are untrusted per ADR 0008. That is meaningful context beyond the annotations, though it stops short of saying what happens for a missing/invalid id.

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?

Front-loaded with the core action and the sibling routing before the caveats, and every clause carries information. The back half is dense with internal jargon ('Wave BI provenance', 'ADR 0008') that could be opaque without project context.

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?

With no output schema, the description still covers source, trust model, and provenance, which is largely sufficient for a thin single-row lookup. It does not indicate what fields a claim row contains or how a not-found id is signalled, a minor 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% and the single parameter already carries a pattern, an example, and the claim_id description. The description repeats the example id but adds no new meaning about the parameter, so the baseline 3 applies.

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 verb and resource (fetch one claim row by claim_id) plus the backing source (data/claims_index.json). The example id makes the identifier shape concrete, and naming list_claims as the browsing counterpart separates it from the sibling tool without needing schema inspection.

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?

Explicitly routes the agent: use this when you have a single claim_id, use list_claims with filters when browsing. That is a named alternative plus the condition that selects it, which is the top of the scale for a one-parameter getter.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the description is not carrying the safety burden. It still adds genuinely new context: unknown ids yield 404, the payload includes follow-up results, and 'modeled, not guaranteed' is an important data-quality caveat an agent would not otherwise know.

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?

Three tight clauses with the action front-loaded, then error semantics, then the reliability caveat. The trailing 'Read-only API, live at https://api.diditwork.org' partly restates readOnlyHint and pads the ending, but the host URL is non-redundant 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 one-parameter read tool with rich annotations and no output schema, the description covers what it returns ('follow-up results'), how it fails (404), and how far to trust the data — nothing an agent needs to invoke it correctly 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?

Schema description coverage is 0%, so the description must carry the parameter meaning, and it does: it names the argument as a record_id and shows the ldg_... form. The example duplicates the schema's own 'examples' entry, limiting added value, but the semantic framing is present.

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 verb and resource: 'Fetch one outcome-ledger record by record_id', plus the scope detail that follow-up results come along. The word 'one' implicitly separates it from the sibling list_ledger_records, but the sibling is never named, so the differentiation is inferential rather than stated.

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?

Usage is implied (single-record lookup when you already hold a ledger id) but never spelled out, and no alternative is named — an agent must infer on its own that list_ledger_records is the way to discover ids. '404 for unknown ids' is useful but is error behavior, not routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description adds value beyond that by disclosing invariants (mixes_units_in_ranking:false, "never invent Accepted", "Never invents CE") and the short-sha256 nature of the fingerprint. It does not describe the response envelope, but the invariants disclosed are exactly what a provenance tool needs.

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?

Front-loaded with the resource and purpose, and every clause carries content, but it is packed into two long run-on sentences with nested parentheticals and internal ticket/policy jargon. Comprehensible but harder to parse than it needs to be.

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?

No output schema exists, so the description must convey the return shape — and it does, by enumerating the key fields (adr_0007_status, claims_index_fingerprint, counts{orgs, interventions, causes, sources_files}). It stops short of a full field listing, but enough is given to decide to call it.

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?

Zero parameters and 100% schema coverage, which is the baseline-4 case — there is nothing for the description to disambiguate. The description correctly avoids inventing parameters.

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?

"API version, discovery links, ... reproducibility audit snapshot fields" names a specific resource and enumerates the concrete fields returned, so an agent knows exactly what this returns. It is clearly distinct from every sibling (get_claim, get_org, etc.), none of which surface provenance metadata, though the sentence is dense and jargon-heavy rather than plainly stated.

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?

"so agents can prove which product_version + data_snapshot_id + claims_index_fingerprint they ranked against" gives the concrete reason to call it: provenance/audit verification. It also names a related focused endpoint (GET /v1/meta/snapshot) with the same audit_snapshot object, but does not state when NOT to use this one.

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

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

It goes far beyond annotations by detailing the exact contents and state of the returned data. Specifying elements like 'decision_brief,' 'donate_url (next_action),' and the distinction between 'modeled: true / guaranteed: false' provides rich, actionable behavioral context about the output.

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 highly dense but structurally effective. It combines the core action, the identification criteria, and the comprehensive data payload in a concise manner without unnecessary jargon.

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 the lack of an output schema, the description provides a complete behavioral contract by listing all major fields returned, including the specific status flags like 'modeled: true / guaranteed: false,' leaving no ambiguity for the agent.

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?

Since schema coverage is 0%, the description must carry all semantic meaning. It successfully defines the input as a 'stable org_id' and clarifies that the input could refer to an organization, program, or fund, thereby enriching the context beyond the pattern matching in 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?

The description clearly states the function: 'Fetch one organization / program / fund record.' It is highly specific about the nature of the record and how it is identified using the 'stable org_id'.

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 establishes a strong context for usage by specifying that it operates on a 'stable org_id.' This inherently suggests that this tool is the mechanism for fetching a known entity, differentiating it from list/search functions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description goes further: it discloses the backing file, the sole human operator, that write_api is always false, that approve/reject is offline file editing, and that agents must never auto-clear trust flags or invent CE/EINs/donate URLs. This is meaningful behavioral context beyond the annotation set.

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 default behavior are front-loaded, and the safety constraints come after, which is a sensible order. It is slightly dense with five clauses, but each sentence carries real operational or safety content, so it is appropriately sized for a read-only queue tool with write-adjacent risks.

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?

With one optional parameter, full schema coverage, and read-only annotations, the description supplies everything needed: what the queue is, whose queue it is, default and historical filtering, and the crucial fact that mutations are offline-only and must not be improvised. No output schema exists, but no return-value details are necessary for a straightforward filtered list.

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% and the schema already documents the status enum and default, so the baseline is 3. The description adds value by explaining what the 'all' enum value means ('pass status=all for history'), which is more than the bare enum list conveys, though the default status=open is repeated from 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?

The description names a specific verb ('Returns items') and resource ('Human exception-review queue'), plus the exact backing store (data/review/queue.json). It also distinguishes this read-only queue from offline approval workflows, so an agent can identify its role without opening the 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?

It states the default (status=open) and explicitly says to pass status=all for history, giving concrete selection guidance. It also clarifies when NOT to use it for writes ('Approve/reject is offline file edit only ... there is no unauthenticated write/approve API'), which is exactly the kind of when/when-not routing an agent needs.

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

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

Annotations already cover read-only, idempotent, non-destructive safety, and the description adds real behavioral context: output is sanitized, a disclaimer is always attached, and deductibility.assert_personal_deductibility is always false. It does not cover error/not-found behavior or freshness of the data, but the added return-value semantics are substantial.

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?

Three short sentences, all load-bearing, with the scoping statement and the safety-critical constraint front-loaded. The terse fragment 'Prefer before asserting US deductibility' costs a little readability but wastes no space.

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?

With no output schema, the description does the necessary work of naming a key returned field and the always-included disclaimer, which is what an agent needs to avoid misuse. Missing only edge-case behavior (unknown org, staleness) for a single-parameter read.

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 0% and the description never mentions org_id, its required status, or the org_ slug format required by the pattern. The schema's pattern and example make the parameter constructible, but the description contributes nothing to parameter meaning.

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 and output shape: a sanitized trust/tax-status summary for an org, plus the always-on disclaimer that comes with it. It is distinguishable from get_org/get_trust by the 'sanitized summary' framing, though it never explicitly contrasts with get_trust, which is the closest sibling.

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 an explicit usage trigger ('Prefer before asserting US deductibility') and a hard prohibition on claiming personal deductibility for a specific donor. No exclusion conditions or named alternative (e.g. get_trust) are given, so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that the output is trust/safety flags and that it gates certain assertions, but it does not describe return fields, freshness, or error behavior.

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?

Two short sentences, front-loaded with the scope and then a strong usage constraint. 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 one-parameter read-only tool, the description covers why and when to call it. Because there is no output schema, however, it leaves the shape of the returned trust and safety flags undefined.

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?

The sole parameter org_id is only implied by 'for an org'; schema description coverage is 0%, although the schema itself supplies a pattern and example. The description does not explain the org identifier format or validation, so it fails to compensate for the low coverage.

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 the resource ('trust and safety flags') and domain ('for an org') and ties it to a concrete decision (US tax deductibility or registry status). It does not explicitly distinguish it from the sibling get_tax tool, but the flags-focused scope is clear.

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?

Explicitly instructs use before asserting US tax deductibility or registry status, which is a clear trigger condition. It does not name alternatives or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare this as a safe, idempotent, read-only, closed-world lookup. The description adds useful context beyond annotations by saying the returned fields should be mapped to recommend query params and that the id feeds create_giving_intent. It does not cover not-found behavior, but the annotations carry most of the safety profile.

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?

Three short sentences, front-loaded with the fetch action, then usage conditions and downstream mapping. Every sentence adds routing or parameter context without waste.

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 simple one-parameter read tool with annotations covering safety and no output schema, the description is nearly complete. It explains what is returned conceptually by saying to map fields to recommend query params, though it could be slightly more explicit about the response shape.

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?

The single id parameter has no schema description coverage, so the description must compensate. It identifies the id as a vp_* preset id and points to list_values_profiles as the source, while the schema supplies the pattern and examples. This is adequate but not rich.

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 states a specific verb and resource: fetch one values-profile preset by id. It also names the distinguishing sibling, list_values_profiles, and clarifies that this returns a single preset rather than a list.

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 explicitly says when to use it: after list_values_profiles or when the donor picked a named preset. It also names downstream usage with create_giving_intent as values_profile_id, which removes ambiguity about routing.

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

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

Beyond the readOnly/idempotent annotations it discloses error behaviour (isError with invalid_filter plus a 'cleaned address'), zero-result behaviour (a coverage field explaining gaps and what to do instead, no guessed rating), and partial_coverage for recognizable-but-unrated charities. These are non-obvious response traits an agent could not infer from annotations or 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?

Front-loads the core purpose, but the opening sentence is a dense, awkward appositive ('The Did it work? charity list, filtered: the charities https://... shows for cause, evaluator (by), measure...'). Several clauses (live API URL, index.json equivalence, coverage, partial_coverage) could be tightened without losing 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?

With no output schema, the description carries the return burden and does much of it: row links to claims file and API record, JSON shape equivalence to index.json, and the coverage/partial_coverage fields. It still leaves the exact top-level response structure (e.g., where count sits, how parameters with counts are shaped) only partially sketched.

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, but the description adds meaning the schema lacks: filters hide only, never reorder or score, and the combined filter set matches the static index.json for the same filter. It does not add per-parameter format detail, but the added filter semantics justify going above 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?

States a specific verb and resource (the charity list) plus the five filter dimensions (cause, evaluator/by, measure, follow-up, word search) and that results come in the page's own order. The 'hide-only, never re-order/score/rank' clause sharply separates it from ranking/compare siblings like compare_charities and recommend_charity.

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 an explicit zero-argument recipe ('call with no arguments to get the full list and every allowed value with its count') and states that out-of-range values return invalid_filter with allowed values, which implies discovery-first usage. It doesn't explicitly say when to reach for compare_charities or search_orgs instead, so it stops short of full alternative routing.

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

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

Annotations already cover read-only/idempotent/closed-world, but the description adds substantive traits they cannot: it copies existing org evaluation claims and never invents CE or claim values, org narrative fields are untrusted per ADR 0008, Wave BI provenance is attached to responses, and 'no figure, rating or order is added.' That is a real trust and provenance model an agent needs when quoting figures.

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 and index location are front-loaded, and the safety constraints come before the response-shape detail. There is mild redundancy between 'never invents CE / claim values' and 'No figure, rating or order is added,' and the single dense paragraph would scan better as separate sentences.

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?

With no output schema, the description has to carry return semantics, and it does describe the decision_brief payload (donate_url next_action, evaluator's fund alternative, like-for-like comparison page, modeled/guaranteed flags) plus provenance. It stops short of describing the claim record fields an agent would receive for each row.

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 would be 3, but the description adds meaning beyond the schema for `verified` — use verified:true with a non-null value when quoting cost-effectiveness — which the schema's plain 'filter on claim.verified' does not convey.

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 states a specific verb and resource ('Read-only flat claims index (data/claims_index.json)') plus the optional filters, which is far more concrete than the bare name/title. It never names the sibling get_claim for single-claim retrieval, so an agent must infer the list-vs-single distinction from the name alone.

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 actionable guidance for filter choice: 'Prefer verified:true + non-null value when quoting cost-effectiveness.' That is a clear usage rule, but there is no statement of when NOT to use this tool or which sibling (get_claim, list_charities, search_orgs) to prefer for adjacent needs.

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

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

Annotations already establish read-only, idempotent, closed-world behavior; the description adds meaningful non-obvious context on top — that the response carries an ADR 0007 disclaimer with mixes_units_in_ranking:false, that boards never cross-mix WELLBYs with lives_saved, and that the tool never invents cross-unit moral weights. The guarantee about board immutability ('frozen') is also useful. It stops short of describing response shape or ordering, so not 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?

Three tight sentences with the source and scope front-loaded, then the two call modes, then the invariants. The ADR reference and unit-mixing clause are dense but carry real behavioral meaning rather than filler.

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?

No output schema, but the description compensates by disclosing the disclaimer field and the no-cross-unit-mixing guarantee that shape the return value, and it covers both zero-arg and one-arg invocations. Only the concrete response structure (board entries, ranking fields) is left unstated, which is a modest gap for a read-only list tool.

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% and the schema already documents both outcome and its alias outcome_preference, including accepted values and the omit-for-all behavior. The description restates the omit/pass semantics and adds that a single family's board is 'frozen ranked', which hints at ordering, but contributes little the schema doesn't already convey. Baseline 3 applies.

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 names a specific resource (per-outcome-family leaderboards sourced from data/ranking/leaderboards.json) and defines scope precisely, including the two modes (all families vs. one frozen board). It never states the verb explicitly ("list") and makes no reference to any sibling tool, so differentiation comes from the resource noun rather than an explicit 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?

"Omit outcome to list all families" and "Pass outcome= to fetch one family's frozen ranked board" give clear mode-selection guidance covering both call patterns. What's missing is any pointer to which sibling to use instead for comparison or impact questions (compare_charities, estimate_impact), so an agent gets context but no exclusions.

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

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

Annotations already cover readOnly/idempotent/non-destructive/openWorld=false, so the bar is lower; the description nonetheless adds real context by disclosing verify-on-read semantics (hash chain + checkpoint + evaluator allowlist + derivability) and that the API is live at a specific host. It stops short of describing pagination or result size limits for a potentially large record list.

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?

Two compact, front-loaded sentences with no wasted preamble; the parenthetical verification clause is dense but earns its place as behavioral context. The trailing host sentence is the weakest element but still informative.

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?

With no output schema and 0% parameter coverage, an agent must guess both the filter semantics and the return shape. The verification-model disclosure partially compensates, making it borderline adequate, but a five-filter list tool deserves at least a hint of ordering, paging, or default behavior.

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 0%, so the prose must carry parameter meaning, but it describes none of the five filters (org_id, status, evaluator, record_kind, intervention_id). Only 'follow-up check dates/status' loosely gestures at status, and 3 enums plus 2 patterns are left to the reader to interpret.

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 verb ('List') and a clearly-scoped resource ('outcome-ledger records'), then glosses the resource as evaluator claim snapshots with provenance hashes and follow-up check dates/status. It distinguishes itself implicitly from get_ledger_record by being the list variant, but never names the sibling or contrasts scope (all vs single).

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 says only what is listed; it never states when to reach for this tool versus get_ledger_record, list_claims, or get_review_queue, and gives no prerequisites or exclusion criteria. Filtering intent is only inferable from the enum parameters, not from the prose.

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

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

Annotations already declare readOnlyHint/idempotentHint, so the safety profile is covered; the description still adds value by specifying which result fields map onto which /v1/recommend inputs and by asserting 'never mutates ranking CE'. This is a genuine behavioral contract beyond the annotations, though 'ranking CE' is an unexplained abbreviation.

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?

Two dense sentences, front-loaded with what it lists and followed by the usage/routing contract; nothing is padding. The arrow notation and 'ranking CE' jargon are compact but slightly opaque, keeping it off a 5.

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 compensates by enumerating the profile fields (outcome, risk, tax, geography, red_lines, non_cash) an agent will receive. Combined with the zero-param schema and read-only annotations, an agent has essentially everything needed to call and consume it.

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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description goes further by explaining how fields in the returned profiles become parameters of other tools (outcome_preference→outcome, id→values_profile_id), which is useful downstream semantics even though it is not about this tool's own input.

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?

Specific verb ('List') plus a precise resource ('static values-profile presets'), with the parenthetical clarifying it is the same catalog used by the demo environment. It implicitly separates itself from get_values_profile by being a listing, but never explicitly says how they differ, so it stops short of a 5.

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?

States an explicit trigger ('Load before recommend when the donor stated preferences') and then routes the output to two named downstream tools — /v1/recommend for the expanded fields and create_giving_intent via values_profile_id. The agent knows both when to call this and what to do with the result.

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

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.

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

The description adds substantial context beyond the annotations: anonymity, no storage of personal or conversation data, standard anonymous request counting, no effect on ratings/rankings/answers, and the self-report being a weak signal rather than proof. These details are consistent with readOnlyHint=true and destructiveHint=false and help the agent understand privacy and impact.

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 required enum are front-loaded, followed by timing, privacy, and interpretation limits. The description is somewhat long and includes a URL and agent-twin context, but most sentences carry useful behavioral or privacy 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 one-parameter, read-only reporting tool with a fully documented enum and no output schema, the description covers purpose, timing, privacy, interpretation limits, and side-effect behavior. An agent has enough information to invoke it correctly without needing return-value details.

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?

The input schema already has 100% description coverage and defines the single enum parameter with detailed meanings for changed, confirmed, and not_deciding. The description reinforces that only the enum is accepted and no free text, ids, amounts, or conversation content are allowed, but it does not add syntax or meaning 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?

The description states a specific verb and resource: anonymously reporting whether the answer changed, confirmed, or left the person not_deciding. It also names the exact enum options and timing, making the tool's purpose unmistakable and distinct from sibling tools like recommend_charity or create_giving_intent.

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 clear timing guidance: call it once, after the person has decided or said they are not deciding. It does not name alternative sibling tools, but no sibling appears to serve the same reporting purpose, so the missing alternatives are minor.

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

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

The description discloses extensive behavior beyond the read-only annotations: empty-result coverage, partial_coverage, fixed refusal answers, no scoring, no fraud checks, no 400 for instruction injection, and numerous response-field semantics. Nothing contradicts the readOnlyHint or destructiveHint=false annotations.

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 an enormous single-paragraph wall of text that catalogs dozens of special answer fields, wave numbers, examples, and policy rules. Although the purpose is front-loaded, the overwhelming majority of sentences are dense routing specifications that make the definition hard to scan.

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?

With no output schema and only 50% schema description coverage, the description carries the burden of explaining return behavior and does so exhaustively: coverage fields, partial_coverage, answer_first, funding_question, request_declined, method answers, and special-case fields. It is more than complete for an agent trying to understand the tool's outputs.

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 50%, and the description partially compensates by mapping the search dimensions to cause, outcome family, and donor intent phrase, and by noting that q and intent are read for fixed answers. It still leaves cause and intent largely undefined and does not specify accepted values beyond examples.

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 opening sentence states a specific verb and resource: heuristic search by cause, outcome family, or donor intent phrase. It distinguishes this from recommend_charity for ranked 'best for outcome' results, but does not differentiate it from siblings such as list_charities, get_org, or compare_charities.

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 one explicit alternative (recommend_charity) and many implicit triggers based on question types, but it never states when to avoid this tool in favor of the other search/list/get/compare siblings. The usage guidance is present but embedded in response-field rules rather than tool-selection guidance.

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

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

Adds substantive traits beyond the readOnly/idempotent annotations: 'Computes nothing: every figure and date is copied whole from a stored value, and the response holds no JSON number' and 'No overall verdict, score, grade or count of strong links: live charities get no worked/didn't-work word.' It also declares the degraded case (covered: false, all links 'Not covered'), which an agent needs to interpret a partial result.

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 is front-loaded, but the middle is a long run-on enumeration of output fields in a single sentence, and the trailing 'Same function as GET /v1/verdict-chain/{org_id}' adds little for an MCP caller. The field list is defensible given no output schema, but the packaging makes it slower to parse than it needs to be.

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?

With no output schema, the description must explain the return shape and does: links fields, weakest_link, open_questions, summary_donor_voice, rung_rules, widest_evidence_gap, better_source, covered. Combined with the no-numbers constraint and the uncovered-charity behavior, an agent has everything needed to call and interpret it.

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 0%, so the description must carry org_id, and it only indirectly does so via 'for one charity' and 'Same function as GET /v1/verdict-chain/{org_id}'. It never states the org_ prefix format, that it must exist, or what happens with an unknown org_id — the schema pattern is the only source for that.

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 ('the verdict chain for one charity, link by link (L0 Defined to L7 Checked)') and a precise scope of source data ('the evidence-gap ledger, our outcome ledger, the evaluator figures... and the verdict procedure'). An agent can tell this apart from get_ledger_record or decision_brief from the sentence alone.

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?

Usage is only implied — the description says what gets returned and notes the fallback behavior for charities without an evidence-gap entry (covered: false, pointer to get_org), which is useful routing. But it never states when to prefer this over siblings like decision_brief, compare_charities, or get_ledger_record, so the agent must infer.

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