foundation-discovery

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

Annotations already mark this as read-only and non-destructive, and the description adds substantial behavioral context beyond that: the 7.5M-edge graph, 2022-2026 IRS data, how funders are merged across peers, that results carry grant evidence, that location only biases peer discovery and never filters funders, and that longer org descriptions match fewer orgs. This is unusually transparent.

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 longer than average but earnestly structured with bold section labels and front-loaded purpose. Each section adds operational value; only minor marketing-style phrasing like 'strongest free-tier prospecting move' is non-essential. Overall it is dense but well-organized.

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 tool with 5 optional parameters, a fallback matching algorithm, and sibling alternatives, the description is complete: it covers inputs, behavior, edge cases, recommended workflow, and downstream follow-up tools. Since an output schema exists, not spelling out return fields is acceptable, and the description even names a returned field (peer_discovery).

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 already 100%, and the description still adds meaningful guidance: peer_orgs is preferred, up to 12 are used, org_description should be a short cause phrase rather than a paragraph, and the matching fallback path is explained. This goes well beyond the schema's field descriptions, especially for the two mutually-conditioned input modes.

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' using a named grant graph. It also explicitly distinguishes this tool from search_funders and search_open_grants, so an agent can immediately tell it apart from siblings.

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 guidance: name 2-5 peers for sharpest results, use org_description only as a fallback, and pair with get_funder_profile/get_foundation_grants for deeper research. It also names the alternatives it is not (search_funders, search_open_grants), making selection unambiguous.

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 readOnlyHint, the description discloses rich behavioral details: it is the reverse of get_foundation_grants, it resolves names via IRS BMF and echoes the resolved recipient, and it clarifies coverage limitations (990-PF only, not government/corporate/donor-advised). It also explains how to interpret empty results, which is important nuanced 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 description is front-loaded with the core purpose, then organized into usage, parameter guidance, and coverage caveats. Each sentence adds value and nothing is redundant; the length is appropriate for the complexity, with clear formatting (COVERAGE in caps) to highlight critical caveats.

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?

The description covers the essential context: data source and time range, inverse relationship to another tool, single-org vs peer scope, parameter resolution behavior, and coverage limitations. The presence of an output schema relieves the need to describe return values, and the annotations cover safety, so this is complete for an agent to invoke 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 all four parameters with descriptions, so baseline is 3. The description adds meaningful usage guidance beyond the schema by explaining the EIN-vs-name precedence and resolution behavior, which helps the agent choose parameters correctly. It does not elaborate on limit/min_amount, but those are already fully described 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?

Description uses a specific verb and resource: 'Find the foundations that have ACTUALLY granted to ONE specific nonprofit', and explicitly names the inverse of get_foundation_grants. It also distinguishes itself from the sibling find_funders_for_peers by contrasting single-org vs several-org use.

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 this tool ('Use this when the question is about a SINGLE org'), gives example queries, and directs multi-org cases to find_funders_for_peers. It also provides parameter selection guidance (prefer recipient_ein, otherwise recipient_name with resolution confirmation).

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 meaningful behavioral context by specifying that it shows financial information over time and calculates trends for assets, grants, and revenue. It also mentions Form 990 or 990-PF, giving additional insight not captured by annotations, though it does not disclose potential limitations like data availability gaps.

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 two sentences long, front-loaded with the primary purpose, and includes supplementary detail about trends and form types without redundancy. Every sentence contributes value.

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 tool has an output schema (not shown) and good annotations, the description is reasonably complete. It explains what data is retrieved, the types of forms covered, and the trend calculation. It could be slightly more explicit about prerequisites (e.g., foundation EIN) but the schema already covers that. Overall 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 covers both parameters (ein and years) with full detail, so description need not add parameter-level meaning. The description's reference to 'over time' and 'trends' implicitly relates to the 'years' parameter, but adds no new semantics beyond the schema. Thus baseline 3 is appropriate.

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 retrieves IRS 990 filing data and calculates financial trends for a foundation. It specifies the resource (IRS 990 filings) and the action (retrieve/show trends), distinguishing it from sibling tools that focus on other aspects like grants or funder profiles.

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 usage for getting financial trends for a foundation, but does not explicitly state when to use this tool versus alternatives like get_funder_stats or search_funders. It provides context (e.g., 'over time', 'year-over-year trends') but lacks direct comparison or exclusion statements.

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?

Even with readOnlyHint=true and destructiveHint=false already covering safety, the description adds significant behavioral context: it merges five distinct stores, each row includes a source field with concrete values, web-extracted records may carry an amount_coverage_note that must be surfaced, original-currency amounts are preserved, and recipient_country reflects the grantee's HQ country rather than implementation location. No annotation contradiction.

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 long, but the tool is genuinely complex and nearly every paragraph earns its place: source enumeration, the data-quality caveat, and the country semantics note are all decision-relevant. It is front-loaded with purpose and scoping, though the detailed store-by-store statistics could be tightened without losing much.

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 8-parameter tool with five merged data sources, the description covers what the tool returns, how to select the right funder identity, what source field values to expect, and an important data-quality caveat to surface. With annotations covering safety and an output schema present, nothing critical 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?

The schema has 100% description coverage, so the baseline is 3 and the description does not need to repeat parameter mechanics. It adds value by explicitly instructing the agent to pass funder_id instead of ein for non-990 funders and by clarifying the semantic of recipient_country beyond the schema's ISO-code guidance. This is enough to raise it slightly 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?

The first sentence clearly states the action ('View grants made by a funder') and the resource scope ('IRS, web-extracted, and registry records'). It goes beyond the title by specifying exactly which kinds of funders and sources are covered, and the 'ANY funder' phrasing helps distinguish it from opportunity-oriented tools like search_open_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 an explicit directive: use this for ANY funder when the user asks about grants given, including non-EIN European funders, and it tells the agent to pass funder_id instead of ein. It does not explicitly name a sibling alternative or state when not to use the tool, though the 'grants made by a funder' framing implies the boundary.

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 provide readOnly/destructive hints, so the description need not repeat them. It adds valuable behavioral context by explaining polymorphic identifier handling (ein vs funder_id with n9f prefix) and the constraint that at least one identifier must be supplied. No contradiction 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 short, front-loaded paragraphs with no filler. Each sentence earns its place: purpose, identifier polymorphism, and when to use it.

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 only two optional parameters, a rich output schema, and strong annotations, the description covers the core workflow and identifier choice completely. It answers the key questions an agent would have about what to pass and when.

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 documents both parameters with 100% coverage, so the baseline is 3. The description adds semantics by grouping the identifiers by funder type (US 990 vs non-990) and reinforcing that search_funders returns both fields, aiding identifier selection.

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 detailed profile information for a specific funder,' which uses a specific verb and resource and immediately distinguishes this from sibling search/stats tools. It also clarifies the scope (specific funder) rather than a list or aggregate.

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 'Use this after searching for funders to get detailed information about a specific one,' giving clear situational context. It does not name alternative tools 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 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 and destructiveHint=false, covering the safety profile. The description adds context about what the tool does (browse codes) and its purpose, but does not disclose any additional behavioral traits such as pagination, result limits, or how outputs are structured. This is acceptable for a simple read-only lookup tool with an output 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?

The description is two well-structured sentences. The first sentence explains what the tool b rowses, and the second adds purpose. There is no fluff, and the key information is front-loaded.

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?

This is a simple tool with two optional parameters, a rich schema, and an output schema, so the description doesn't need to over-explain. It covers the overall purpose and usage context. However, it could slightly improve by explicitly noting that either parameter option can be used independently or together, though the schema already implies this.

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 each parameter has a clear description. The tool description itself does not add extra meaning beyond the schema, but the baseline of 3 is appropriate because the schema already explains the parameters thoroughly.

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 identifies the tool as a browser for NTEE classification codes, with a specific purpose: helping find the right code for searching or understanding a foundation's focus area. It uses the verb 'browse' plus the resource 'NTEE codes,' and the context about nonprofit classification distinguishes it from sibling tools about funders and grants, though it doesn't explicitly compare to a 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?

The description states when to use the tool ('find the right NTEE code for searching or understanding a foundation's focus area') but provides no exclusions or alternatives. Since there are no direct sibling tools for NTEE codes, the guidance is adequate but not explicit about when not to use it.

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 declare readOnlyHint=true and destructiveHint=false. The description adds meaningful context beyond that: it explains the data pipeline (weekly scrape of ~50K pages) and the classification model (GPT-5.4-mini), plus explicit exclusions that set result expectations. This is useful behavioral info not present in 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 well-structured: a clear opening sentence, a data-source note, a bulleted category list, and a concise exclusions list. While lengthy due to the category taxonomy, every section serves a distinct purpose—either clarifying parameter values or setting result expectations. Nothing is redundant.

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 13-parameter search tool with full schema coverage and an output schema, the description is remarkably complete. It covers domain boundaries, data freshness, classification methodology, category definitions, and explicit exclusions. The agent receives all necessary context to decide when and how 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?

The schema has 100% parameter description coverage, so it already carries much of the semantic load. The main description adds significant value by defining all 8 categories for `category`/`exclude_categories`, including concrete role examples and exclusions—information the schema references but does not enumerate. Other parameters are already well-documented 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 opens with a specific verb+resource: 'Search OPEN PHILANTHROPY JOBS at grantmaking foundations.' It clearly identifies the tool's function and distinguishes it from sibling tools like search_funders (which searches funders) and search_open_grants (which searches 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 provides clear context about scope and exclusions, including a detailed 'What's excluded by design' list and category definitions. However, it does not explicitly name alternative tools for other query types (e.g., 'for grants use search_open_grants'), so it stops short of full comparative 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 readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond that: data source (IRS data), ranking behavior (multi-word searches ranked by relevance vs. simple browse/name fallback ordered by total assets), and the distinction that search_funders surfaces funders that may operate on LOI/relationship/annual cycles rather than live calls. No contradiction 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 compact and well-organized: a one-line summary, a usage paragraph, and a clearly flagged IMPORTANT routing note. Every sentence earns its place, and the most decision-relevant distinction (when to use search_open_grants instead) is prominently separated.

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 read-only search tool with 15 optional parameters fully documented in the schema and an output schema present, the description covers the key usage scenarios, ranking behavior, and sibling-tool routing. Nothing an agent needs to correctly select and invoke 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 each of the 15 parameters has rich, example-laden documentation. The description itself only names the high-level search dimensions (name, topic, location), so it does not add meaning beyond the schema. Baseline 3 is appropriate when the schema carries the full parameter-load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Look up grantmaking organizations by name, topic, or location') and further specifies the 174K+ IRS-based dataset and the name/topic-signal search mechanism. It clearly distinguishes this tool from search_open_grants and other funder-focused siblings.

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 use the tool ('when you know the funder's name, want aligned funders for a cause area, or want to browse by location/size/NTEE code') and gives an explicit exclusion: use search_open_grants for active grant programs or RFPs. This is model guidance with a named alternative.

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 description correctly does not need to restate safety. It adds meaningful behavioral context by describing the underlying IRS data source, the ~2M-org scope, and the exact recipient-side funding signals returned in each result. No contradiction with annotations is present.

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 longer than minimal, but every section earns its place: the opening defines scope, the middle explains result content, and the closing provides tool-selection guidance. It is structured with clear headings and front-loaded with the most important distinction (grantee vs. funder). Slightly verbose because of the inline code fields, but well organized.

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 tool with an output schema, the description is complete: it explains the domain, the result payload, the key tool-routing decisions, and the likely downstream workflow. The schema covers the remaining parameter details, and the output schema handles return-value expectations. Nothing essential is missing for correct tool selection and 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 87%, so the schema already carries most parameter meaning. The description adds useful high-level context about the result fields (total_grants_received, funder_count, etc.) and mentions broad use cases, but it does not add per-parameter guidance beyond what the schema provides. Baseline 3 is appropriate.

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 subject ('Search the ~2M-org universe of US nonprofits (IRS Business Master File)') and explicitly positions it as the 'RECIPIENT / grantee side, distinct from search_funders'. This clearly differentiates it from its primary sibling tool, so an agent can identify what it does 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 'CHOOSING THE RIGHT TOOL' section provides explicit conditional routing: use search_funders when the intent is to find funders to apply to, use search_nonprofits for recipient benchmarking, and use get_foundation_grants/search_funders after finding a well-funded peer. This is clear, actionable guidance with named alternatives.

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 readOnlyHint=true, destructiveHint=false, but the description goes well beyond: it discloses the search engine behavior (natural language understanding, stemming, query syntax with examples), explains the geographic ranking logic (place-specific funders ranked first), what happens with unrecognized country values (broadens rather than empties), and the internal workaround for 'topic' alias. No contradictions.

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 well-structured with sections (for-profit applicants, supported sources, search semantics) and front-loaded with the core purpose. It could be slightly tighter (e.g., the historical 'by TOPIC' note is edge-case), but every sentence adds value—no filler, good readability.

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?

Despite 13 parameters, no output schema (yet has one), and no required params, the description covers all major behavioral aspects: query syntax, filtering options, entity-type-aware defaults, geographic nuances, and browsing mode. No glaring gaps remain for an agent to misuse the 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%, yet the description adds critical meaning: for_profit_applicant bridges to an alternative capital pool, the 'country' parameter explains multi-tier geographic ranking, and the 'topic' alias documents a real user-facing issue. This transforms flat schema descriptions into actionable guidance.

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 uses a specific verb ('Search') and resource ('open grant opportunities'), clearly identifying the domain (Kindora's foundation corpus plus federal and state government grants). It distinguishes from siblings like 'search_funders' or 'get_funder_profile' by focusing on grant opportunities rather than funder profiles.

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 provides explicit guidance on when to use the for_profit_applicant parameter, contrasts the default nonprofit pool, and explains when to use the 'country' parameter over 'state' for international queries. It also advises against filtering by 'source' to government-only due to sparse results, offering clear alternatives and context.

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