990.tax nonprofit lookup

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so safety is covered. The description adds real domain behavior beyond that: it explains the IRC 6033(j) three-consecutive-missing-years revocation rule and names the date fields returned, which is substantive context an agent needs to interpret results. It stops short of describing response shape or behavior for orgs never granted exemption.

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

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

Two sentences, the core question front-loaded, with the parenthetical listing return fields and the second sentence supplying the legal rule that motivates the tool. No filler or repetition — every clause 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 no output schema and only one parameter, the description carries the burden of explaining returns, and it does so by naming revocation, posting and reinstatement dates plus missing-year flags. Minor gaps remain: no error/empty-result behavior and no note on what a clean status looks like.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter carries its own format guidance (9 digits, dash optional). The description adds no EIN-level detail beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb and subject: whether the IRS automatically revoked the organization's exemption, plus which of the last three ended accounting years have no return on file. The parenthetical enumerates returned data (revocation, posting, reinstatement dates), which clearly separates it from siblings like get_nonprofit_profile or search_nonprofits.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the domain phrasing — an agent can infer this is the tool for exemption-revocation questions — but the description never states when to prefer it over get_nonprofit_profile or search_nonprofits, nor any preconditions (e.g. needing a valid EIN already resolved). No exclusions or alternatives are named.

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

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

Annotations already declare this a read-only, idempotent, non-destructive, closed-world lookup, so the safety profile is covered. The description adds genuine value beyond that by disclosing the shape of the answer: plain-English meaning, the underlying IRS rule text, and remediation guidance. It does not say what happens for an unrecognized or non-MEF code, which keeps it short of full 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?

One sentence, front-loaded with the deliverable and immediately followed by the scope and a code example. Nothing is wasted and nothing important is buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must describe the return value, and it does so by enumerating the three components it produces. For a single-parameter lookup with full annotation coverage that is nearly sufficient; only the miss behavior (unknown or malformed code) is left unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single 'code' parameter is documented with an example and length bounds, so the schema carries the parameter burden. The description repeats the same example format and adds the form-family scope, but contributes no new syntax or validation detail beyond the schema.

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

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

The description names a specific resource (an IRS Modernized e-File business rule reject code), scopes it to four named forms, and gives a concrete example ('R0000-922-01'). No sibling tool touches reject codes, so an agent can distinguish this tool from check_exempt_status, which_990_form, and the rest 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?

The context of use is implied rather than stated: an agent must infer that this is for decoding a rejection after a failed e-file submission. There are no explicit exclusions or pointers to alternatives (none exist among the siblings, but the description doesn't say so). Adequate but leaves the when-to-call trigger 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 establish readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuine computation semantics beyond that: dates are shifted off weekends and legal holidays, Form 8868 extension applies except for 990-N, and late-filing consequences are included. It omits any note on how the extension is computed or whether the EIN path derives the fiscal year end.

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 returned values are front-loaded, and the two trailing clauses on tax_year and input choice are economical. The opening sentence is heavily comma-loaded with a five-item list, which is slightly dense but each element is substantive rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing returns and does so fully: due date, adjusted date, extension, days remaining, penalties. Combined with the tax-year and default-form guidance, an agent has what it needs to call this correctly; only the EIN-to-fiscal-year derivation is left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75% and the description compensates for the one undocumented parameter by defining tax_year precisely (the calendar year the accounting year begins in, defaulting to the latest ended year), which the schema leaves silent. The 'month or EIN' phrasing signals the two alternative lookup paths, but the interaction between ein and fiscal_year_end_month is not resolved.

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

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

The description names a specific resource (the Form 990 due date) and enumerates the exact outputs: the due date adjusted off weekends/holidays, the Form 8868 extended date, days remaining, and late-filing consequences. An agent can distinguish this from siblings like which_990_form (form selection) or check_exempt_status 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?

"Give the fiscal year end month or an EIN" tells the agent exactly what input to supply and implies either identifier path works, which is meaningful since there are zero required parameters. It does not name alternatives or state when not to use it (e.g., versus which_990_form for picking a form type), so it stops 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 declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds real behavioral context beyond that: result caps of up to 5 years of financials and up to 15 officers, plus the source forms (990/990-EZ/990-PF) and Publication 78 deductibility provenance.

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

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

Two sentences, front-loaded with the core record contents and then the opt-in sections. The long field enumeration is dense but every item conveys a distinct returnable fact, so nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description carries the full burden of explaining return values, and it does so field by field with caps and data sources. For a two-parameter read tool this leaves no meaningful gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the baseline is 3. The description does add value by explaining what each optional section actually contains (financial line items, officer compensation, e-Postcards plus e-filed returns), which goes beyond the bare enum labels.

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

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

The description names a specific resource (one organization's IRS record, keyed by EIN) and enumerates the exact fields returned, so an agent knows precisely what it gets. It stops short of differentiating itself from the overlapping sibling check_exempt_status, which also reports exemption status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied through the optional-section framing: omit 'include' for the compact profile, add sections for depth. There is no explicit when-to-use/when-not guidance and no named alternative for the overlapping exempt-status or search tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-open-world behavior, so the description does not need to restate safety. It adds useful behavioral context by naming the data source (IRS public data), the metrics available (active organizations, 990-N filers, revocations, revenue, assets, employees, pay), and the extra breakdowns returned for national scope. That goes beyond structured fields.

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 and dense with relevant information, with no filler sentences. It is a single long sentence, which makes it slightly harder to scan, but every clause contributes to scope or metric understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description carries the burden of explaining what is returned. It does so by listing the metrics and national-level breakdowns, which is fairly complete for a statistics tool. Minor gaps remain around output format or pagination, but those are less critical for a read-only aggregate 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 coverage is 67%, and the schema itself documents state and ntee_major with length constraints and examples. The description reinforces the three scope values and clarifies that NTEE uses a single major category letter, but it adds little syntax or format detail beyond the schema. 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?

States a specific verb and resource: 'Counts and totals for US tax-exempt organizations from IRS public data.' It also enumerates the three supported scopes (national, one state, one NTEE major category), which clearly distinguishes it from sibling tools like get_nonprofit_profile and search_nonprofits.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool by listing the available scopes and metrics, but it does not explicitly contrast this with alternatives such as get_top_nonprofits or search_nonprofits. An agent can infer that this is for aggregate statistics, but no exclusion or routing guidance is provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the data provenance ('e-filed Form 990 returns') and the list-size constraint, but says nothing about entry shape, ranking basis, or whether results are cached or paginated.

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?

A single dense sentence that front-loads the data source and then enumerates categories and the size constraint. No filler, though the 'national (25) or per state (10)' shorthand requires a moment to parse.

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 three-parameter read tool with no output schema, the definition covers what to request but not what comes back (e.g., whether entries include name, EIN, revenue amount, or rank). An agent can invoke it correctly but cannot anticipate the response structure.

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 67%, and the description adds real meaning beyond the schema: it clarifies that national lists go up to 25 while state-scoped lists go to 10, which explains the `limit` maximum=25 and why it may effectively be capped lower when `state` is supplied. The `list` enum values are paraphrased in prose but not individually described.

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

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

States a specific resource (ranked lists from e-filed Form 990 returns) and enumerates the five ranking categories that map to the `list` enum (highest-paid executives, largest by revenue, top fundraising, richest by net assets, biggest employers). An agent can tell this is a rankings tool, though it doesn't explicitly contrast itself with siblings like get_nonprofit_stats or search_nonprofits.

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 parenthetical 'national (25) or per state (10)' implies the selection rule for the `state` parameter, which is genuinely useful usage context. However, there is no explicit when-to-use/when-not guidance or named alternative tool for cases where the agent wants a profile, stats, or a free-text search.

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 read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real value beyond that: it discloses the data source (IRS records), the result cap (up to 10), and the exact fields returned including exempt-status categories. It does not mention match behavior (partial vs exact) or failure/empty-result handling.

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

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

Two sentences, front-loaded with the action and scope, followed by the return payload. Every clause carries information an agent needs, with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description appropriately spells out the returned fields and the result cap, which is the key missing structured data. The only gap is the absence of any note on match semantics or how the optional state filter interacts with 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%, so query, limit and state are all self-documenting in the schema. The description reinforces that query accepts name or EIN but adds no syntax, matching, or state-filter guidance beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('Find US tax-exempt organizations by name or EIN in IRS records') and grounds it in a named data source. It does not explicitly contrast itself with get_nonprofit_profile or get_top_nonprofits, but the lightweight-match framing makes its role reasonably clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by 'by name or EIN' and by the description of the compact result set, which suggests this is the lookup/entry point. There is no explicit guidance on when to pick this over get_nonprofit_profile for details, nor any stated exclusions or prerequisites.

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

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

The annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds real value by disclosing the underlying decision rule, the BMF fallback for missing amounts when an EIN is supplied, and that the answer is cited to the IRS rule. It does not explain how missing amounts are handled without an EIN, which is the main unresolved 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 two dense sentences that front-load the core question and its answer options before adding the EIN lookup detail. Every clause carries information; there is no 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 tool with six fully optional parameters and no output schema, the description supplies enough context to call the tool correctly: the thresholds to reason about, the fallback data source, and the citation behavior. The only real gap is the behavior with no arguments and whether a partial answer is returned when neither an EIN nor the amounts are available.

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 high at 83%, so the baseline is a 3, but the description clearly adds meaning beyond it: it ties gross_receipts to the $50,000 / $200,000 thresholds and total_assets to the $500,000 cutoff, which the schema does not do. It also explains that is_church leads to 'none' as an outcome. The two boolean flags, is_private_foundation and is_509a3_supporting_org, are not addressed in the description, though their schema descriptions partially compensate.

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 tool name is a specific question, and the description immediately answers it: it names the resource (the annual return / Form 990 family) and enumerates the exact possible outcomes (990-N, 990-EZ, 990, 990-PF, or none). The decision criteria for each outcome are stated inline, so it is clearly distinguishable from siblings like get_filing_due_date or check_exempt_status.

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 usage context is implied by the thresholds and the note that an EIN triggers a Business Master File lookup for missing amounts. However, the description never says when to choose this over check_exempt_status or get_filing_due_date, and it doesn't say what happens if the agent supplies no arguments at all, which matters because all six parameters are optional.

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