foundation-discovery

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

The description adds rich behavioral context beyond the readOnlyHint/destructiveHint annotations: it explains the collaborative-filtering algorithm, merges funders across peers, ranks funders by number of peers funded, and states that every result carries real grant evidence. It also details fallback behavior when using org_description and clarifies that location only biases peer discovery, never filters funders – all valuable disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections (HOW IT WORKS, INPUTS, RECOMMENDED WORKFLOW), bolded key terms, and bullet lists. It is moderately long but every sentence earns its place – no redundancy, no filler. Front-loaded with the core value proposition and distinctiveness.

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's complexity (5 params, output schema, annotations), the description covers inputs, fallbacks, algorithm, output content, and even suggests deeper investigation via get_funder_profile/get_foundation_grants. It is fully complete for an agent to decide when and how to invoke it, and what to expect in return.

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 already covers parameters at 100%, but the description adds meaningful semantics: peer_orgs is preferred and graph-keyed by EIN, up to 12 peers used, org_description as a fallback that resolves via keyword over IRS BMF, and location's non-filtering role. This goes beyond the schema's basic descriptions, though not enough to reach a 5 since the schema is already strong.

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 finds grantmakers that have funded organizations similar to the caller's, using a specific data source (IRS 990-PF grant graph). It explicitly distinguishes itself from sibling tools search_funders (name/topic lookup) and search_open_grants (active RFPs), making its unique purpose 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?

Provides explicit when-to-use guidance: calls it the 'strongest free-tier prospecting move' and names alternatives with their different scopes. Includes a recommended workflow (establish mission, name 2-5 peers, call tool) and clarifies which input to prefer (peer_orgs over org_description). This is exemplary usage 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?

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns by saying 'View grants.' It adds substantial behavioral context: merging five stores, the source field per row, the amount_coverage_note caveat for web-extracted rows, and the recipient_country interpretation (HQ country not necessarily implementation site). No 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 every sentence carries weight. It front-loads the purpose, uses a numbered list for data stores, and explains caveats and usage in a structured way. For a tool with 8 parameters and multiple sources, the level of detail is justified and 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?

Despite having an output schema, the description adds necessary context about the source field, amount_coverage_note in data_quality, and recipient_country semantics. It covers the data sources, parameter choice, and caveats, making it complete for an AI agent to select and 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?

Input schema covers all 8 parameters (100% coverage), so baseline is 3. The description adds value by clarifying the choice between ein and funder_id ('pass funder_id instead of ein'), which is crucial for correct parameter selection. It also reinforces the recipient_country semantics. This goes beyond schema descriptions.

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: 'View grants made by a funder across IRS, web-extracted, and registry records.' It clearly lists the five data stores and the output's source field, which distinguishes this tool from siblings like search_open_grants or get_funder_profile.

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 says 'Use this for ANY funder when the user asks about grants given, including European funders without an EIN (pass funder_id instead of ein).' It also references search_funders/get_funder_profile for obtaining funder_id. However, it does not explicitly state when not to use the tool or mention alternatives like search_open_grants, so it's clear but lacks explicit 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 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, so the tool is known to be safe. The description adds meaningful behavioral context: multi-word searches are ranked by relevance, fallback results are ordered by total assets, and it 'searches 174K+ grantmaking organizations from IRS data.' It also notes funders may operate by relationship/LOI/annual cycle, which is useful nuance. It doesn't overreach, so a 4 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?

The description is efficiently organized: a one-sentence purpose, a data/scope sentence, a list of use cases, and an explicit comparison to the sibling tool. Every sentence earns its place, and the most critical information is front-loaded. No filler 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 tool's complexity (15 optional parameters) and the presence of a complete input schema plus an output schema, the description is sufficiently complete. It clarifies the tool's scope, data source, search behavior, and sibling distinction, which is enough for an agent to select and call it correctly. No gaps that hinder usage.

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%, with each of the 15 parameters already documented with examples and guidance. The main description only hints at parameters ('name, topic, or location', 'location/size/NTEE code'), which adds little beyond the schema. The baseline of 3 is correct because the schema carries the semantic weight.

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 clear verb and resource: 'Look up grantmaking organizations by name, topic, or location.' It further specifies it searches 174K+ organizations from IRS data. The distinction from sibling search_open_grants is made explicit, making the tool's role 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?

It provides explicit use cases: 'when you know the funder's name, want aligned funders for a cause area, or want to browse by location/size/NTEE code.' It also directly instructs when not to use it: 'Use search_open_grants when the user needs active grant programs or RFPs.' This leaves no ambiguity about tool selection.

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 significant behavioral context beyond that: it details the data source (IRS Business Master File), the scope (~2M orgs), and the returned fields (990 financials, total_grants_received, funder_count, etc.). This gives the agent a clear picture of what the tool returns without contradicting 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 moderately long but well-structured with headers, bold text, and dash lists. Each section earns its place: the purpose, the output signals, and the tool-selection guidance. It is front-loaded with the main purpose and then provides actionable context, though it could be slightly more concise.

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's complexity (15 parameters, 12 sibling tools, output schema present), the description is highly complete. It explains the data universe, the results' content, and the decision flow between search_nonprofits, search_funders, and get_foundation_grants. An agent would have enough context to select and invoke the tool correctly even without schema browsing.

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 high (87%), so parameters are already well-documented in the schema. The description adds context about key concepts like `funder_count` and `min_received` filters but does not systematically restate parameter meanings. The baseline of 3 is appropriate because the description complements the schema without needing to compensate for gaps.

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: 'Search the ~2M-org universe of US nonprofits (IRS Business Master File)'. It explicitly distinguishes itself from sibling search_funders, making the purpose unmistakable and differentiating it from closely related 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?

The 'CHOOSING THE RIGHT TOOL' section provides explicit when-to-use guidance with concrete alternatives: 'Want FUNDERS to apply to → use search_funders. Want to research/benchmark RECIPIENT nonprofits... → use search_nonprofits.' It even suggests follow-up tools after finding well-funded peers, covering both use and non-use cases.

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 annotations (read-only, non-destructive), the description reveals critical behavior: the default pool is 501(c)(3)-shaped and excludes for-profit capital instruments, full-text search uses stemming and natural language query parsing, and no-query browsing returns results sorted by deadlines. It also documents the rejected state+country mix and topic alias behavior, providing substantial transparency.

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-organized with clear section headings (FOR-PROFIT APPLICANTS, Query syntax), but it is lengthy. Some content duplicates schema descriptions (e.g., exclusion syntax appears both in query param and the dedicated syntax block). Given the 13 parameters and complex behaviors, the length is mostly justified, but trimming redundancy would improve conciseness.

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 fully covers the tool's complexity: both data sources, applicant-type behavior, search semantics, geographic filtering (state vs. country), deadline lookahead, and query syntax. With an output schema present and the description addressing edge cases, this is a complete and self-sufficient tool description.

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?

Although the schema covers 100% of parameters, the description enriches semantics significantly—especially for query (syntax with quoted phrases and exclusions), for_profit_applicant (routes to capital pools), source (preference to omit), and state/country (geographic nuance). These details go far beyond the schema's basic descriptions, adding actionable meaning for 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 clearly states the tool searches open grant opportunities from two distinct sources: Kindora's foundation-program corpus and federal government grants. The verb 'search' and the explicit resource differentiate it from sibling tools like search_funders and find_funders_of_nonprofit, making the purpose unmistakable.

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 extensive when-to-use guidance, including for-profit vs. nonprofit routing, when to omit the source filter ('PREFER omitting this'), and international vs. US-state filtering ('Use this instead of state for international queries'). It also warns against mixing state with non-US country and explains the topic alias handling, offering clear alternatives within the tool.

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