foundation-discovery

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

Annotations already cover read-only/open-world/destructive, but the description adds substantial non-schema behavior: the ranking rule (funders shared across multiple peers rank highest), the evidence returned per result, the prompt-injection handling via `untrusted_fields`, and the exclusion of DAF sponsors/own-program funders into `via_intermediaries` with `giving_basis`.

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 claim and organized under HOW IT WORKS / INPUTS / RECOMMENDED WORKFLOW headers, so it is easy to scan. It is long and a few points (e.g. repeating that location only biases peer discovery) are restated in both schema and description.

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 a multi-parameter, zero-required tool with an output schema, the description still explains the mechanism, the input selection logic, the discovery pass reported in `peer_discovery`, and how excluded funders surface. Nothing an agent needs in order to call 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 coverage is 100%, so baseline is 3, but the description adds real meaning: peer_orgs are keyed by recipient EIN and capped at 12 used, and org_description is a short cause phrase where longer text matches fewer orgs (name/BMF/NTEE matching, not mission text). Some of this overlaps the schema's own parameter notes, keeping it just short of 5.

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 ('find grantmakers that have actually funded organizations like the caller's') plus the data basis (7.5M-edge who-funds-whom grant graph, IRS 990-PF 2022-2026). It explicitly distinguishes itself from the two closest siblings, search_funders (name/topic lookup) and search_open_grants (active RFPs).

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 when-to-use framing ('strongest free-tier prospecting move'), a named preferred input (peer_orgs) with a stated fallback (org_description) and the condition that selects it. It also spells out a recommended workflow and which sibling tools to use to deepen a candidate.

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 give readOnly/destructive/openWorld, but the description adds real behavioral context beyond them: the coverage boundary (government grants and most DAF funding are absent), the interpretation of an empty result ('no tracked funder reported or announced a grant', not 'no funders'), the untrusted_fields safety note, and the identity-resolution behavior with name_match semantics. This is exactly the extra context the annotations do not carry.

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 purpose and the sibling routing first, then resolution mechanics, then coverage caveats — a sensible ordering. It is on the long side for a 6-parameter tool, with dense em-dash asides, but every section carries information an agent needs; little is pure 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?

An output schema exists, so return-shape details are not required here. Given that, the description covers everything the agent needs to call correctly: which identifier to pass, what happens on name resolution failure, and how to interpret empty versus populated results.

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 each parameter, so the baseline is 3. The description lifts it by explaining precedence (alias keys accepted, recipient_ein/recipient_name win), why EIN is more precise, and what the resolution echo (recipient, name_match exact vs approximate, candidates fallback) means for the caller.

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+resource with scope: 'funders that have ACTUALLY granted to ONE specific nonprofit', and immediately frames it as 'the reverse of get_foundation_grants' over a named data source (IRS 990-PF grant graph plus announced records). This is enough to distinguish it from get_foundation_grants (opposite direction) and find_funders_for_peers (one org vs many) without opening any 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?

Explicitly names the use case ('who funds Greater Chicago Food Depository?') and the exclusion with the alternative: 'To aggregate the same signal across SEVERAL peer orgs, use find_funders_for_peers instead.' It also specifies the parameter-selection preference (recipient_ein when known, else recipient_name).

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/destructiveHint/openWorldHint, but the description adds real behavioral context beyond them: a prompt-injection warning that text in `untrusted_fields` must be treated as data, and the graceful-redirect-instead-of-error behavior for non-990 funders. That is exactly the kind of non-obvious behavior an agent 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-loads the core purpose then adds the security note and routing rules in short paragraphs. Slight redundancy between the funder_id explanation here and in the schema, and the bullet-ish layout is a bit sprawling, but every sentence carries 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 an output schema present, return values need not be explained; the description still covers the non-obvious pieces an agent needs — filer eligibility, id resolution, redirect behavior, and untrusted-content handling. Nothing material is missing 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 coverage is 100%, so baseline is 3; the description earns above that by explaining the ein/funder_id interchangeability and the resolution rules ('usf:<ein>' routes to 990, non-990 ids redirect). It restates a fair amount of what the schema already documents, so it does not reach 5.

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 ('Get IRS 990 filing summary and financial trends for a foundation') and immediately scopes it to Form 990 / 990-PF filers. It is clearly distinguishable from siblings like get_funder_stats and search_funders, which it names.

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 when-to-use and when-not-to-use guidance: 'US 990 filers only', how to supply ein or funder_id, and that non-990 funders 'return a clean redirect to get_funder_stats(funder_id=...)' rather than an error. It also tells the agent where funder_id comes from (search_funders).

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 safety profile (readOnlyHint, destructiveHint, openWorldHint), but the description adds substantial behavioral context beyond them: a prompt-injection warning about untrusted_fields, the five merged data stores and their scope, and the amount_coverage_note caveat in data_quality that the agent is told to surface. That is exactly the extra context the annotations cannot provide.

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 the trust/untrusted data warning are front-loaded, and the multi-paragraph structure groups related facts coherently. It is on the long side and includes provenance details (e.g. "~143K US private foundations") that are helpful but not strictly necessary, so it is dense rather than wasteful.

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 an output schema exists, the description need not document return values, yet it still explains the source field values, the data_quality caveat, and the recipient_country semantics. Nothing an agent needs to call this 8-parameter tool correctly appears to be 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%, so the baseline is 3. The description goes modestly beyond it by explaining the ein/funder_id substitution logic and emphasizing that funder_id is the path for non-990 (European) funders, which clarifies which identifier to reach for. It mostly parallels the schema, so it does not reach a 5.

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 (view) and resource (grants made by a funder) and immediately scopes it to three record classes, which differentiates it from siblings like search_open_grants (grants available to apply for) and get_funder_profile. An agent can identify the tool's job 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?

"Use this for ANY funder when the user asks about grants given" gives explicit when-to-use guidance, and it names the ein-vs-funder_id condition for European funders. It does not, however, name a competing sibling tool or state when to prefer an alternative, so it falls short of full 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real value beyond them: it warns that organization/funder/job-posting text is returned in `untrusted_fields` and must be treated as data, not instructions — a prompt-injection defense the annotations cannot express.

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?

Content is front-loaded with the one-line purpose, then the injection warning, then the identifier rules, then usage — a sensible order. It is slightly longer than strictly needed, with some overlap between the description's identifier explanation and the schema's, but nothing is wasted or 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?

An output schema exists, so return values need not be described, and the description still flags the untrusted_fields element the caller must handle. Combined with the identifier polymorphism rules and usage context, an agent has everything needed to call this 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 description coverage is 100%, so the baseline would be 3. The description earns above baseline by explaining the polymorphic routing rule (ein for US 990 funders vs funder_id for non-990 funders) and by stating the 'at least one identifier' constraint that the schema itself does not encode, since both params default to null and are optional.

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 ('Get detailed profile information for a specific funder'), which is clearly distinct from the search_* siblings. It names search_funders as the upstream step, but does not distinguish itself from near-neighbors like get_funder_stats or get_990_summary, so it stops short of full sibling differentiation.

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 says to use it 'after searching for funders to get detailed information about a specific one,' which gives the agent a clear trigger condition. It also states the identifier requirement ('At least one identifier must be supplied'), though it gives no explicit when-not-to-use guidance versus the stats/summary siblings.

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 and destructiveHint=false. The description adds behavioral context by enumerating the data sources (IRS 990-PF, web-extracted, 360Giving, CRA T3010, ACRI) and the types of aggregate outputs. It does not disclose potential limitations such as data completeness, but the additions are valuable beyond the 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 front-loaded with the main purpose, followed by a concise explanation of data sources and outputs, then the parameter selection. Each sentence contributes new information, with no fluff or redundancy. It is appropriately sized for the tool's complexity.

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 an output schema exists, the description does not need to detail return values. It explains the tool's scope, data sources, and parameter usage. It lacks explicit notes on edge cases (e.g., funders with no data), but overall it is complete enough for an agent to invoke the tool 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 covers 100% of parameters. The description adds a decision rule for choosing between ein and funder_id based on funder type, which is not fully articulated in the schema. It also reinforces the formatting details (hyphens allowed). This extra guidance meaningfully assists the agent.

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 'Get comprehensive giving statistics for a funder,' clearly stating the verb and resource. It further specifies what the statistics include (lifetime totals, focus areas, geographic distribution, trends) and the data sources used, effectively distinguishing it from siblings like get_funder_profile or get_foundation_grants.

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 explicit guidance on when to use each parameter: 'Pass ein for US 990 foundations, or funder_id for non-990 funders.' This provides clear context for tool invocation, though it does not explicitly contrast with alternative tools or state 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description correctly reinforces that this is a reference/browse operation but adds no extra behavioral context such as result volume, ordering, or coverage limits, so a 3 is appropriate.

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 with no filler, front-loading the tool's identity before the contextual explanation. It is slightly padded by the second sentence restating what NTEE codes are, which a taxonomy-savvy agent may not need.

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?

An output schema exists, so return values need not be described, and the 0-required-parameter design means the tool can be called with no arguments. The one real gap is that the description omits how the two optional parameters select different browse modes, but coverage is otherwise adequate.

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 itself gives concrete examples for both `query` ("K31", "K6A", "education") and `category` ("A" for Arts, etc.). The description supplies no additional parameter meaning, 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?

The description pairs a specific verb ("Browse") with a specific resource (NTEE classification codes) and expands the acronym, explaining these codes classify nonprofits by primary purpose. No sibling tool touches taxonomy lookup, so an agent can distinguish it immediately from search_funders, get_funder_profile, etc.

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 downstream purpose ("find the right NTEE code for searching or understanding a foundation's focus area"), which implies when an agent should reach for it. However, it never explains the two distinct modes the schema exposes (lookup by code vs. free-text search vs. category browse), nor does it name any alternative tool or condition.

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/destructiveHint=false, but the description goes well beyond them: it discloses a privacy suppression path (an org that opted out returns only name plus note), partial-section behavior, an `unavailable` marker for unreadable sources, and a prompt-injection warning about `untrusted_fields`. That is exactly the kind of behavioral context annotations cannot carry.

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 overall payload scope, then cleanly segmented by 'Never included:', `unavailable`, and `untrusted_fields` clauses. It is long, but the length is justified by the breadth of returned content; a reader can stop after the first clause and still know what the tool is.

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?

Although an output schema exists (so return structure needn't be spelled out), the description still covers the edge behaviors an agent must anticipate: suppressed records, missing sections, unreadable sources, and untrusted text fields. Nothing needed to call or interpret this 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?

Schema description coverage is 100%, and the org_id schema already spells out the EIN and SCHEME-VALUE formats. The description's two example calls restate those same accepted formats rather than adding new syntax or constraints, so the schema is doing the heavy lifting and 3 is the appropriate 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 (get) and resource (one organization's full profile) and enumerates the exact content domains returned, so an agent can distinguish it from sibling tools like get_990_summary or get_funder_profile without opening the schema. The 'Everything Kindora holds about one nonprofit, NGO or social enterprise' framing makes the scope unambiguous.

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 clear context ('for a funder researching it'), which is the working condition that selects this tool. It does not, however, name alternatives or exclusions — it never says to use search_organizations first to obtain the org_id or why to prefer this over get_990_summary for a narrow 990 lookup, leaving routing to 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the return structure (status, version, environment) and the connectivity check behavior, which goes beyond the annotation-only information.

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 extremely concise, front-loaded with the purpose, and follows with a clear bulleted list of return fields. No filler or redundant content.

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 zero-parameter health check tool, the description fully covers its purpose and return data. The output structure is described, and no additional context is needed given the tool's simplicity and the supporting annotations.

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 has zero parameters, so schema coverage is 100%. There is nothing for the description to add about parameters. Baseline for zero-param tools is 4, and no explanation is needed.

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 'Check server health and connectivity' with a specific verb and resource. This uniquely distinguishes it from sibling tools, which all focus on funder/nonprofit data operations.

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 purpose is unambiguous and provides clear context for when to use this tool: when you need to verify server health or connectivity. It does not explicitly list alternatives or exclusions, but the domain differentiation from siblings makes the usage context evident.

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 indicate readOnlyHint=true and destructiveHint=false, so the description only needs to add extra behavioral context. It does so by explaining the tool's dual behavior (list all vs. details for a specific tool) and mentioning what the help includes (parameters, examples, related tools). No contradictions with 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 three concise sentences with the main purpose front-loaded. Every sentence adds useful information without fluff or redundancy.

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 simple schema, rich annotations, and the presence of an output schema, the description fully covers the tool's behavior. It explains both usage modes and what to expect in return, leaving no significant gaps.

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% for the one parameter, so the baseline is 3. The description adds value beyond the schema by explicitly stating that calling without parameters shows all tools, and providing a tool name gets detailed help—this clarifies the optional parameter's behavioral effect.

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 tool lists available MCP tools and provides detailed help. It uses a specific verb and resource, and it distinguishes itself well from sibling tools which all focus on domain-specific queries like funder or grant searches.

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 explicitly states when to use the tool ('to discover what tools are available and how to use them') and explains the two call modes (no parameters vs. with a tool name). It does not explicitly mention when not to use it or contrast with alternatives, but the context is clear given the nature of the tool.

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 safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real value beyond them: a prompt-injection warning about `untrusted_fields` (treat text as data, never instructions) and provenance context (weekly scrape of ~50K funder careers pages). It omits rate limits, pagination, and result-count 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?

The purpose and the security warning are front-loaded, and the category block is dense but each line carries mapping information. The prose wraps are a bit loose and the section could be tightened, but no sentence is 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?

For a 15-parameter read tool with an output schema, the description supplies the essential missing piece — the category taxonomy the schema defers to — plus scope boundaries and injection handling. The main gap is not stating its relationship to sibling tools, which matters given 13 siblings in a crowded namespace.

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 nonetheless adds meaning the schema cannot: the `category` schema entry only says 'One of the 8 philanthropy categories above', so the description's taxonomy definitions are what actually make that parameter usable, including the subtle development_for_grantmaking exclusion.

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 ('Search OPEN PHILANTHROPY JOBS at grantmaking foundations') and pins the domain precisely (roles that give away money, run philanthropic programs, executive leadership). It also enumerates the 8-category taxonomy and explicit exclusions, which lets an agent distinguish it from siblings like search_open_grants and search_funders without opening any 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 clear context for when this applies via the 8 category definitions and a 'What's excluded by design' list, and it tells the agent to use the `category` param to filter. It does not, however, explicitly name when to prefer a sibling such as search_open_grants or search_funders; that compositional pattern appears only in the schema, not the description.

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 safety profile (readOnly, non-destructive, closed-world), yet the description still adds real behavioral context: the `untrusted_fields` prompt-injection boundary telling the agent to treat funder/job text as data never instructions, plus result-ordering behavior (relevance ranking for multi-word vs. total-assets order for browse/name fallback). It does not discuss pagination limits or how many results a browse returns by default, keeping 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?

Front-loaded with purpose, then usage, then the sibling redirect — good ordering with no filler sentences. The untrusted-fields warning sits between purpose and usage and slightly interrupts the flow, and the dataset-size sentence borders on decorative, but overall it is tight for a tool this complex.

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 an 18-parameter, zero-required search tool with an output schema, the description covers what to search, when to prefer it, its sibling alternative, and the trust boundary for returned text. Gaps are minor: no mention that all filters are optional/combinable, and no guidance on sensible filter combinations or result-set size expectations.

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 baseline is 3; the description goes further by explaining the ranking semantics of `query` (multi-word = relevance, browse/name fallback = total assets) and the metro-vs-grantee geography framing ('most geo asks are about where grants LAND'). Those are meaning-level distinctions the agent needs for parameter choice, though the per-parameter details themselves live 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?

Opens with a concrete verb+resource+facets: 'Look up grantmaking organizations by name, topic, or location.' It further pins down the dataset (174K+ IRS-sourced grantmakers) and explicitly distinguishes itself from search_open_grants by contrast (aligned grantmakers vs. live programs/RFPs). An agent can tell exactly what this returns 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?

Gives three positive triggers ('know the funder's name', 'want aligned funders for a cause area', 'browse by location/size/NTEE code') and a named exclusion with rationale: use search_open_grants when the user needs active programs or RFPs, because this tool covers relationship/LOI/annual-cycle funders. That is explicit when/when-not/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 only establish read-only safety; the description adds substantial non-obvious behavior: a prompt-injection warning naming `untrusted_fields`, the paging contract (`has_more` -> `page_offset` = `next_page_offset`), a silent fallback where an unrecognized metro does not error but returns `geo_notice`, and `unavailable_fields` for unreadable data. It further discloses that thesis mode only reaches semantically profiled orgs while `query` reaches all — a critical eligibility constraint no annotation covers.

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 purpose, then routing, then thesis mode, then paging — a sensible escalation. Dense rather than padded, but it is long and the routing bullet restating 'use search_nonprofits for recipient research' partially repeats the opening scope sentence.

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 20-parameter tool with two operating modes, the description covers mode selection, filter interactions, sort defaults, paging, and data-trust caveats. An output schema exists, yet the field glossary (total_grants_received caveat, funder_count, avg_grant_size_received being per-funder) prevents misreading results — nothing an agent needs 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 90%, so the baseline is 3, and the description goes beyond it by explaining the thesis-mode parameter cluster (thesis, technology_role, ai_usage, ruling_date_from, sort_by/legibility_counterweight) as a coherent mode rather than isolated fields, and by flagging min_received as the key grantee-benchmarking filter. It omits any explanation of min_revenue/max_revenue, which the schema leaves undescribed.

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+resource+scope: searching the ~2M-org IRS Business Master File universe of US nonprofits, explicitly the grantee side. It immediately distinguishes itself from search_funders (grantmaker side) and later from search_organizations (non-US) and get_organization_profile, so an agent can route without opening a 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?

The 'CHOOSING THE RIGHT TOOL' block gives explicit when-to-use (benchmark peers, 'who received $X', cause landscape), when-not (non-US orgs, single-profile lookups, funder-side questions), and names the exact alternative for each. It also hands off to find_funders_of_nonprofit(recipient_ein=...) as a follow-up step.

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, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: text is untrusted and echoed in `untrusted_fields` (prompt-injection guidance), and `geo_notice`/`applied_geography` must be relayed to the user. These are valuable additions, though rate limits and result-set sizing are left implicit and the untrusted-fields note is somewhat buried mid-paragraph.

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?

Well front-loaded: corpus scope, untrusted-data warning, then the for-profit carve-out, then mechanics. However, the for-profit story is told twice (opening paragraph and the parameter), and the source-filter advice repeats what the schema already says, adding avoidable length.

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?

An output schema exists, so return values needn't be enumerated, yet the description still names the two response fields an agent must act on (`untrusted_fields`, `geo_notice`). Combined with query syntax, geography interplay, and the for-profit routing rule, an agent has everything needed for a 14-parameter tool with zero required fields.

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 baseline is 3, but the description goes beyond the schema by explaining the stemming/tokenization model, showing combined query syntax (phrase + term + exclusion), clarifying state-vs-country precedence and the mixing rejection, and narrating the for-profit capital pool. The topic/query alias precedence is left to the schema, preventing a 5.

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+resource (search open grant opportunities) and immediately scopes the corpus: Kindora's foundation programs plus Grants.gov and state portals. It is clearly distinguishable from siblings like search_funders, get_foundation_grants, and search_funder_jobs, which target funder entities rather than open opportunities.

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 usage: use state for geographic focus, use country instead of state for international queries (state would error), prefer omitting source because government-only often returns zero, and pass for_profit_applicant=true when the applicant is a company since the default pool is 501(c)(3)-shaped. It also documents browsing mode when query is empty, giving a clear when-to-use path.

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, non-destructive, closed-world safety profile, and the description adds substantial behavior beyond them: paging contract (has_more / next_page_offset / page_offset), a hard 5,000-row paging cap with the `paging_limit_reached` flag and the instruction to narrow rather than page further. It also flags that organization-authored text appears in `untrusted_fields` and must be treated as data, not instructions.

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 purpose, then searchable dimensions, then chaining, paging, and safety guidance, closing with four compact examples. Despite covering eight parameters plus paging and a prompt-injection caveat, no sentence is redundant or restates the schema verbatim.

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 an eight-input, zero-required-parameter search tool with an output schema present, the description supplies everything an agent needs: eligibility constraint, filtering dimensions, sibling disambiguation, pagination lifecycle, the 5,000-row ceiling, untrusted-content handling, and the follow-up call. Return-value detail is rightly omitted since the output schema covers 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 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: `topic` is matched against keywords and program names on the extracted website profile (the schema only says 'what the organization works on'), and `org_roles` values are attributed to the organization's own website. It also explains the `org_id` -> get_organization_profile handoff, which the schema does not.

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 states a concrete verb and resource ('Find nonprofits, NGOs and social enterprises in every country Kindora holds') and enumerates the underlying registries (IRS, CRA, Charity Commission, ACNC, Kenya NGO board, MIT Solve), which pins down the corpus precisely. It also names the sibling it is not (search_nonprofits) for US IRS data, so an agent can route correctly 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?

Explicit when-to-use is stated ('For funders sourcing grantees outside a name list'), the alternative for US grant-ranked searching is named with its differentiator ('search_nonprofits goes deeper on IRS data'), and there is a stated minimum constraint ('Give at least a name, a topic, a role, or non-US countries'). Four worked examples cover the main invocation shapes including exclude_countries.

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 declare a non-read-only, non-idempotent write but say nothing about the human flow. The description adds what happens on write ('Kindora records the request and emails the person a link. It returns no link'), the six-digit email confirmation, that the person starts introductions themselves, that nobody browses the profile, and that Kindora uses nothing until they act. This is substantive disclosure beyond the safety annotations, and it does not contradict them.

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 the sibling distinction are front-loaded, and the approval gate is stated plainly. It is long, and parts (the enumerated profile fields, the asks description) repeat the nested schema's own description, but nearly every sentence carries workflow or messaging instruction that an agent needs. Slight redundancy keeps it from 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?

For a nested-object, human-approval-gated write tool this covers the full pipeline: brief authoring, consent step, email-code confirmation, and post-signup behavior. It also supplies messaging guidance ('Kindora Connect calls this "About you", never a profile; use those words with the person'). With an output schema present, no return-value explanation is required, so nothing needed 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%, so the baseline is 3, but the description goes further: it names the profile fields to include, singles out `asks` as 'the most useful field' with concrete guidance on what belongs in it (up to three one-liners, problem/peer/funding), and explains the approval meaning of person_approved_sending. This adds real semantic value over the schema, though the field list is partially a restatement of the covered properties.

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+resource+scope ('Set up a PERSON's Kindora Connect profile') and characterizes the underlying capability (one-to-one introductions). Crucially, it names the sibling it is not and the condition that selects the sibling ('For an organization's funder search, use start_kindora_profile'), so an agent can disambiguate 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 the trigger ('when the person asks for that'), the alternative tool for the org case, and the full approval gate ('show the person the whole brief... ask whether to send it. Call only after they say yes, with person_approved_sending set to true'). Both when-to-use and the when-not are explicit.

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 only say readOnlyHint=false, destructiveHint=false, openWorldHint=false, idempotentHint=false. The description goes well beyond that: it writes, Kindora records the request, emails the person a link, returns no link, and the person must confirm a six-digit code and review every field before any profile exists. These are real downstream side effects an agent could not infer from the 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?

Front-loaded with purpose, then the consent procedure, then the write/return behavior — a logical order with little waste. It is on the long side and includes one throwaway line ('The brief's fields are in this tool's input schema'), but every other sentence carries operational weight.

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 complex tool with nested objects, 4 parameters, and an output schema, the description covers everything the agent still needs: the consent gate, what to include in the brief, private-data handling, and what the call does and does not return. Return-value detail is correctly left to the output schema.

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 schema already documents the fields and a baseline of 3 applies. The description adds genuine curation guidance on top: what belongs in the brief, that website-or-EIN is required, and the semantic intent of keep_private ('anything they do not want on the profile') and person_approved_sending (true only after consent). It stops short of explaining field formats the schema already covers.

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 ('Set up a nonprofit organization on Kindora from a brief') and names the triggering condition. No sibling tool does anything comparable, so it is unambiguously distinguishable from the search/lookup tools.

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 states when to call ('when the person asks for that') and lays out the required preconditions: write the brief from the conversation, show it to the person, disclose that it will be sent with their email, ask permission, and call only after a yes with person_approved_sending=true. This is a full when/when-not protocol, not inference.

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