frc-mcp

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

Adds substantial behavior beyond the annotations: 'deterministic verdict', 'checked with fixed patterns, no model', and enumerates the return values (pass / needs_qualifier / block with reason code, plus a verbatim safe sentence, required attribution, and rule receipt). The rule mode also enumerates misclassification codes (STALE_VALUE, VALUE_FROM_OTHER_RULE, VALUE_MISMATCH/UNVERIFIED_VALUE). This is rich context the annotations cannot carry.

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

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

Purpose is front-loaded, but the bulk is dense, comma-spliced, parenthetical-heavy prose (mode C in particular is one long run-on). The content is largely useful, yet the packing makes it harder to scan than it needs to be. Efficient in word count but not in structure.

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

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

For a complex, no-output-schema tool the description is close to self-sufficient: it explains the verdict shape, reason codes, and the receipt, so an agent knows what comes back without an output schema. The main residual gap is the incomplete flag-to-parameter mapping given 11% schema coverage.

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

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

Schema coverage is only 11% across 9 params, so the description must compensate. It maps several flags loosely (population, period, scope, cause, individual prediction, lender recommendation, legal conclusion) and mentions qualifier/attribution outcomes, but never explicitly links each named flag to its parameter (e.g. qualifier_dropped, attribution_present, scope_beyond_universe) nor explains the flag-vs-sentence precedence. Partial compensation only.

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 precise verb+resource+scope: 'Checks a proposed statement of a FinanceRateCalc figure against that figure's published use contract'. An agent can immediately distinguish this checker from the data-fetching siblings (get_rule, resolve_fha_annual_mip, screen_counterparties). The three input modes further pin down what the tool operates on.

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?

Names the workflow position ('so the sentence can be verified before it is written') and gives an explicit exclusion: 'NOT FOR: figures published by anyone other than FinanceRateCalc'. It also disambiguates the three modes (flags, sentence, rule sentence) by input shape. It stops short of routing to a specific sibling tool, so it is strong but not a full when/when-not/alternative set.

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, closed-world, but the description adds substantial context beyond them: the source record (public CFPB HMDA 2025, actions 1,2,3, loan_type 2), the scope limit to the 100 largest FHA lenders, the important base-size caveat that the denied share is computed on a larger base than the published denial rate and both are returned, plus a non-prediction caveat and license attribution. That is exactly the extra disclosure annotations cannot carry.

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

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

Front-loads the answerable questions, then scope, then caveats and attribution — a sensible order with no filler sentences. It is dense and long-ish, and the five quoted example questions could be trimmed, but each block (answers / not-for / source / caveat) earns its place.

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

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

With no output schema, the description carries the return-shape burden and does so: five outcome shares plus the approved-not-accepted share of approvals, each with its receipt, for national or a single top-100 lender. Source, population filters, and interpretation caveats are all present, leaving nothing an agent needs before calling it.

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

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

Schema coverage is 100% and the single optional `lender` param is fully documented (name, slug or LEI; omit for national). The description corroborates the 'nationally or for one of the 100 largest FHA lenders' scope but adds no format or resolution detail beyond the schema, so the 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: returns the five HMDA ends of an application (originated, approved-not-accepted, denied, withdrawn, closed for incompleteness) as shares of actions 1-5, plus the approved-not-accepted share of approvals. It also disambiguates from the related but different published denial rate (22.1% of decisioned applications), so an agent can tell it apart from the denial-stat siblings without opening a schema.

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

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

The 'ANSWERS:' list gives five concrete question shapes that select this tool, and the 'NOT FOR:' clause explicitly excludes causal explanation, lender quality, and individual outcomes. It does not name the sibling tool an agent should use instead for the excluded questions (e.g. get_denial_reason_shares or get_lender_denial_stats), so routing is strong on when-to-use but not on 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 already cover the safety profile (readOnly, idempotent, openWorld=false), and the description adds substantive behavior: the minimum-cell rule and suppression of small cells, publication scope (CFPB HMDA 2025, actions 1,2,3, loan_type 2), and an explicit not-a-prediction caveat. This is exactly the extra context annotations cannot carry.

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

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

Front-loaded with ANSWERS questions, then PARAM, Returns, and NOT FOR blocks, so an agent can scan quickly. Dense and mostly waste-free, though the quoted example questions add retrieval-oriented verbosity rather than direct instruction.

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

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

With no output schema, the description carries the return-value burden and does so reasonably, describing per-cell gap changes plus cell counts and the minimum-cell rule. It could specify the response shape or pagination more concretely, but for a single-optional-param read tool it is nearly complete.

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?

Only one parameter and schema description coverage is 100% – the schema already documents name, 20-char LEI, and the omit-to-list-all behavior. The description's "PARAM: lender name or slug" adds a 'slug' phrasing not in the schema, but otherwise does not deepen parameter meaning beyond structured data. 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: returns how a lender's peer-adjusted denial gap varies across published cells (state x loan amount x income x DTI x CLTV), with cell counts and the minimum-cell rule. The cell/conditional framing distinguishes it from flat siblings like get_lender_denial_stats and get_metro_lender_gap without requiring a schema read.

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 trigger questions ("does this lender's strictness depend on loan size or leverage") and a clear exclusion block ("NOT FOR: suppressed small cells, or any individual prediction"). It stops short of naming which sibling to use instead for metro-level or summary views, so it is clear context plus exclusions rather than full alternative routing.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds substantial context beyond them: the data source (public CFPB HMDA 2025 record, actions 1,2,3; loan_type 2), the sampling frame (95 of the 100 largest lenders that report reasons), and the semantic caveat that reason fields are not a partition and shares need not sum to 100. It also clarifies the output is an observation, not a prediction.

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

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

Front-loaded with the questions answered and the single parameter, followed by the exclusion and provenance. Dense but each sentence carries information; the licensing/attribution line is boilerplate but required for use of the source data.

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

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

With no output schema, the description still specifies the returned quantities (median and max share per reason, top lender per reason) and the key interpretation caveat about shares not summing to 100. An agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100% and there is a single optional param, so the baseline is 3. The description adds meaning beyond the schema by explaining the effect of omitting lender (cross-lender medians) versus supplying one, which an agent would otherwise have to infer.

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 concrete questions it answers and then states precisely what it returns: median and maximum share of each HMDA denial reason across the reporting largest lenders, plus the lender carrying the highest share of each. This is a specific verb+resource and distinguishes it from siblings like get_lender_denial_stats and get_state_denial_stats.

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

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

It gives explicit usage: pass optional lender, omit for cross-lender medians. It also states an exclusion ('NOT FOR: why a particular application was denied') and the analytical boundary (historical observation, not a prediction about any individual application). Nothing about when to choose this over siblings is left to inference.

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

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

Annotations already declare readOnly/idempotent/closed-world, yet the description goes well beyond them: it discloses that the figure is associational not causal, that HMDA carries no credit scores, the exact data provenance (CFPB HMDA 2025, actions 1,2,3, loan_type 2), the sample size, and the McFadden range. That is rich behavioral context an agent could not get from 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 'ANSWERS:' and 'NOT FOR:' labels front-load the key information and each clause carries signal (headline statistic, caveat, provenance, license). It is dense but slightly overpacked, with the attribution and dataset-provenance tail being useful but not essential to invocation.

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 parameters, no output schema and safety already covered by annotations, the description fully compensates by describing the return value (the variance decomposition and headline 38%/859,090/McFadden figures), its interpretation limits, and data source. An agent has everything needed to select and trust the result.

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?

There are zero input parameters, so the schema cannot be under-documented; per the rubric this sets a baseline of 4. The description adds no parameter syntax because none exists, which is appropriate rather than deficient.

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

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

The description states a specific verb and resource ('Returns the variance decomposition: lender identity is associated with about 38 percent of the explainable variation in FHA denial outcomes'), which is concrete and quantitative. It implicitly distinguishes itself from siblings like get_lender_denial_stats and get_conditional_door_map by framing the output as a single aggregate decomposition, but it never names an alternative tool, so sibling differentiation is inferential rather than explicit.

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 'ANSWERS:' framing gives clear positive usage contexts and the 'NOT FOR:' clause explicitly excludes causal claims and individual estimates, which is strong when-not guidance. However, it never routes the agent to the sibling tool to use instead (e.g., for per-lender or individual-level questions), leaving the alternative choice to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: the data provenance (CFPB HMDA 2025 record), the exact filter methodology (actions 1,2,3; loan_type 2), the applicant-mix caveat that any comparison must carry, and an explicit 'not a prediction' disclaimer.

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

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

Front-loads the answerable questions and then labels each block (PARAM, COVERS ONLY, NOT FOR), which is easy to scan. It is dense and somewhat verbose with repeated question variants, but each section carries routing or scope 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?

With no output schema, the description compensates by enumerating what is returned (volume, denial rate, rank, caveat) and by bounding the population covered. An agent has everything needed to call it and interpret the result correctly.

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

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

Schema description coverage is 100% for the single 'lender' parameter, so the schema already documents accepted formats. The description's 'PARAM: lender name, slug or LEI' restates rather than extends that, so the baseline 3 applies.

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

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

States a specific resource (a lender's FHA denial rate) with concrete example questions and a clear scope (2025 decisioned volume, denial rate, rank). It is readily distinguishable from siblings like get_state_denial_stats and get_national_fha_stats by naming the lender-level unit of analysis.

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 triggers (the quoted user questions) and explicit exclusions under 'NOT FOR: whether a person will be approved, or lenders outside that set', plus a stated coverage limit of the 100 largest FHA lenders. Nothing about routing is left 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 cover read-only, idempotent, non-destructive and closed-world, so the bar is lower, yet the description still adds material context: the 100-decisioned-application inclusion threshold, the underlying source slice (CFPB HMDA 2025, actions 1,2,3, loan_type 2), the fact it is a historical observation and not a prediction, and the CC BY 4.0 attribution requirement.

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

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

Front-loads the ANSWER queries, then PARAM, then Returns, then NOT FOR, then caveats and attribution — a clean priority order. The trailing licensing sentence is necessary for compliance but is the one part that does not help invocation.

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 full burden of describing the return value and does so: a claim passport containing lowest/highest lender denial rates, the gap in points, counts and a source reference. Combined with the inclusion threshold and provenance notes, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% and the single 'metro' parameter is already documented with the same name-or-slug example, so the description's 'PARAM: metro name or slug' adds nothing 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+resource (returns the lender denial-rate spread within a single metro) and pins it with a concrete example (Cleveland, 73.7 points, 6.4 vs 80.1). It is clearly distinguishable from siblings like get_lender_denial_stats, get_state_denial_stats and get_national_fha_stats because the scoping unit — one metro — is stated up front.

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 when-to-use as four literal user questions, plus explicit exclusions: not ZIP/neighbourhood questions, and never as evidence a lender acted improperly. It does not name the sibling an agent should use instead for those excluded cases, which is the only gap.

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

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

Annotations already cover readOnly/idempotent/non-destructive/closed-world, so the bar is lower. The description nonetheless adds meaningful context beyond structured fields: the exact denominator definition (actions 1,2,3; loan_type 2; reverse mortgages excluded), the warning that commonly published 13.6% figures are a different universe, and the 'not a prediction' caveat. It stops short of detailing response shape or correction specifics, but it is well above the annotation baseline.

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

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

Front-loaded with the answering questions and the NOT FOR routing before the provenance tail, so an agent can decide quickly. It is somewhat long (the inline figures and attribution could be trimmed), but nearly every sentence carries routing or quoting 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?

For a no-parameter static lookup with no output schema, the description supplies the returned figure, its universe, provenance, and the quoting caveat — everything an agent needs to use the result correctly without a return-value schema.

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

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

Zero parameters, so the schema imposes no burden and the baseline is 4. The description correctly avoids inventing parameter detail and instead scopes the tool's fixed universe.

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 exactly what it returns — the national 2025 FHA denial rate with its universe — and explicitly differentiates from siblings by excluding state/lender/metro breakdowns and pointing to 'the dedicated tools'. An agent can distinguish this from get_state_denial_stats or get_lender_denial_stats 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?

Opens with a concrete 'ANSWERS' list of natural-language questions, then a 'NOT FOR' list naming the excluded universes (conventional/VA/USDA, purchase-only, other years, state/lender/metro) and where to go instead. Both when-to-use and when-not-to-use are explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description still adds meaningful behavioral context beyond that: it enumerates the returned artifact (cells, effective dates, issuer document, required qualifiers, what the table does not establish, sha256), which is valuable since no output schema exists.

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 ANSWSERS/PARAM/NOT FOR labeling front-loads the useful content and the whole thing is compact. The test-result sentence (3/25 without the file vs 25/25 with it) is slightly promotional, but it is a single clause and arguably earns its place as justification for invoking the tool.

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 optional parameter, the description covers what an agent needs: what questions it answers, how to source the id, what the payload contains, and the temporal/index boundary. The only gap is not naming a sibling when routing away from this tool.

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

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

Schema description coverage is 100% and the schema already documents rule_id and the omit-to-list behavior, so the baseline is 3. The description adds value by stating the id comes "from the index" and by confirming the omit case lists every published rule, clarifying where the identifier is discovered rather than just its format.

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 gives a specific resource (dated regulatory rule table) and concrete question examples ("what is the current FHA loan limit", "which FHA MIP table is in force") that make the tool's purpose unmistakable. It does not, however, distinguish itself from closely related siblings such as resolve_fha_annual_mip, which reads as overlapping with the MIP-table example.

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 framed by four representative questions plus an explicit "NOT FOR" clause excluding rules absent from the index and anything predating the effective date. This is clear when/when-not guidance, but it stops short of pointing to a sibling alternative for the excluded cases or for the overlapping MIP-resolution case.

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 a safe, idempotent read, and the description adds substantial context beyond them: the underlying data source (CFPB HMDA 2025, actions 1,2,3; loan_type 2), the disclosure limit on unpublished middle bands, the caveat that it is not a prediction about an individual application, and the observed 1.19x–4.45x range.

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?

It is front-loaded and sectioned (ANSWERS / PARAM / Returns / NOT FOR / attribution), so it scans well. It runs long, however — the four sample queries and the specific Idaho figures are retrieval aids that border on padding for an agent that already has the title and schema.

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

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

With no output schema, the description carries the return burden and does so: denial rates for both bands, the ratio, the ranking, and a discrepancy note. Combined with the methodology and caveats, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% and there is a single optional param, so the baseline is 3; the description earns extra by explaining what omitting the parameter produces (a ranked list), which the schema's 'optional' marker does not convey.

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

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

The description states a specific computed metric (small-loan denial penalty, i.e. denial-rate ratio for small vs large loans) scoped by state, and names the exact bands (<$150K vs >$250K). It is clearly distinguishable from siblings like get_state_denial_stats or get_national_fha_stats, which do not isolate the size penalty.

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

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

It gives an explicit selection rule ('optional two-letter state; omit for the ranked list') and a clear exclusion ('NOT FOR: loan sizes between the bands, which are not published'). It stops short of naming an alternative sibling for the excluded case, so it is strong but not fully routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds genuinely new context: the data source (CFPB HMDA 2025, actions 1,2,3; loan_type 2), the nature of the result (historical observation, not a prediction about an individual application), and the national benchmark (22.1 percent). It does not discuss caching or return shape in more detail, but the added provenance goes well 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 dense but deliberately structured with ANSWERS / PARAM / NOT FOR labels, front-loading the question forms before constraints. Every clause adds routing, parameter, provenance, or disclaimer value, though the attribution and provenance sentences could be trimmed slightly.

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

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

With no output schema, the description still characterizes the return ('state 2025 rate and counts against the national 22.1 percent'), plus provenance, scope limits, alternatives, and a misuse disclaimer. Nothing an agent needs to call this single-parameter read correctly is missing.

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

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

Schema description coverage is 0% and the only schema constraint is min/maxLength 2, so the description carries the full burden: 'two-letter USPS code only (OH, TX); full names are rejected.' That states both the accepted format and the failure mode, which the schema alone cannot convey.

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

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

The description names a specific resource (state-level FHA denial rate for 2025) and frames it as answering concrete questions, e.g. 'what is the FHA denial rate in <state>'. It also explicitly carves itself out from siblings covering metro/city (get_metro_lender_gap) and lender-level questions, so an agent can pick it without opening another schema.

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

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

It gives explicit when-to-use triggers via the 'ANSWERS:' question list and explicit when-not-to-use with named alternatives ('NOT FOR: metro or city questions (use get_metro_lender_gap) or lender-level questions'). Nothing about routing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds meaningful context beyond them: results are screenable without uploading anything, they are an observation from the public CFPB HMDA 2025 record (actions 1,2,3; loan_type 2), and explicitly not a prediction about any individual application.

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 "ANSWERS:" prefix front-loads the user intents, and the core return statement follows immediately. The trailing data-source, disclaimer, and CC BY attribution sentences are somewhat tangential to tool selection but short and not bloated.

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 no-parameter list tool with no output schema, the description explains what is returned (cohorts with size and definition), how the returned ids are consumed (by run_cohort), and the epistemic caveats. Nothing needed to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing schema-side that the description needs to compensate for. It adds no parameter guidance, but none is possible or required.

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 (returns public/published cohorts) plus concrete return content (size, definition) and explicitly distinguishes itself from run_cohort by noting the cohort ids it lists are what run_cohort accepts. An agent can tell it apart from the get_* siblings without opening schemas.

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?

Frames usage with the user questions it answers ("can I screen a group of lenders", "show me an example screen") and notes it needs no upload, which implies it is the discovery step before run_cohort. It names the downstream tool but gives no explicit when-not-to-use or exclusion conditions.

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 the safe read profile (readOnly, idempotent, closed-world), so the description earns credit for going further: it discloses the data lineage (CFPB HMDA 2025, actions 1,2,3, loan_type 2), the hard scope cap of 100 lenders, the 'historical observation, not a prediction' caveat, and attribution terms. It stops short of describing pagination or return ordering mechanics.

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

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

Front-loaded with ANSWERS, then NOT FOR, then provenance, then attribution — a clean decision-oriented ordering with no repeated content. The licensing/attribution sentence is somewhat peripheral but justifiable for a public-data tool.

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 list with no output schema, the description names the returned fields, the population (top 100 FHA lenders), and the source record, which is enough to invoke correctly. The undocumented limit parameter is the main residual gap.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. Its quoted questions ('denies the most or the fewest', 'how wide is the spread') implicitly convey the sort dimension matching highest_denial/lowest_denial, but the parameters are never named and 'limit' is entirely unaddressed. Partial compensation only.

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

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

States a specific resource and scope: the ranked list of the 100 largest FHA lenders with name, slug, rate and volume, plus a concrete data point (2025 span 1.8–78.7 percent). The purpose is unmistakable, but it never names a sibling tool to differentiate from, e.g. get_lender_denial_stats, so it falls short of the 5 bar.

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 'ANSWERS' block gives concrete triggering questions ('which FHA lender denies the most', 'rank FHA lenders by denial rate') and the 'NOT FOR' block explicitly excludes lenders outside the top 100 and any apply-here recommendation. Clear use context and exclusions are present, though no alternative tool is named for the excluded 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?

With readOnly/idempotent annotations already covering safety, the description adds real substance: it discloses the return payload (annual rate bps, upfront rate, matched cell, rule id with effective date and sha256, quotable sentence) and the failure mode (CONDITION_MISSING block, no number). This is exactly the behavioral context annotations do not carry.

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

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

Dense but front-loaded: ANSWERS, PARAMS, then NOT FOR. Every sentence earns its place; the eleven-cell rationale justifies the no-guess behavior in one clause.

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

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

No output schema, yet the description fully specifies return fields and the error shape. For a four-param, zero-required lookup with an unconventional failure mode, the definition gives the agent everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema lacks: ltv_pct as 'e.g. 96.5', base_loan_amount as before upfront MIP financed, term_years, and the date format. It names each parameter and clarifies that a missing one triggers the CONDITION_MISSING path, which is 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?

States a specific verb (resolve) and resource (the FHA annual MIP cell) and front-loads a natural-language example of the exact question it answers. Clearly distinguishable from siblings like get_rule or get_national_fha_stats.

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

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

Explicit 'NOT FOR' clause excludes pre-2023-03-20 cases, HECM/reverse, Title I, and payment figures. Adds a behavioral rule: if a parameter is missing it returns CONDITION_MISSING rather than guessing, and explains why (eleven cells, a guess is wrong more often than right).

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial context on top: what is returned, that only a free preview is available without a human-purchased licence, the underlying data provenance (CFPB HMDA 2025, actions 1-3, loan_type 2), and an explicit screening-not-misconduct caveat.

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?

Compact and front-loaded with the answering phrases and the key parameter, then the return shape. The telegraphic 'ANSWERS:/PARAM:' fragments and trailing attribution/legal lines make it dense rather than flowing, but little is truly 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?

With no output schema, the description steps in to describe the return (observed vs expected denial rate, coverage flags, method version) and the licensing gate, which is what an agent needs. It omits failure modes for an invalid cohort_id and does not detail the requested_format enum.

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%: cohort_id and license_key are documented in-schema, but requested_format's enum has no description. The description adds partial value ('cohort id from list_cohorts', the preview/licence distinction implying license_key), yet never explains the summary vs evidence_brief choice.

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 ('Run a published cohort', returns the peer-adjusted screen: observed vs expected denial rate, coverage flags, method version), and names list_cohorts as the source of cohort_id. It never contrasts itself with the many sibling screening/stat tools (screen_counterparties, get_lender_denial_stats), so sibling differentiation is only partial.

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 trigger utterances ('run the screen on <cohort>', 'how do these lenders compare against expectation') and states where cohort_id comes from (list_cohorts), plus the free-preview-vs-licence condition. It offers no when-not-to-use guidance or named alternative among the 15 siblings.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), yet the description adds materially: public LEIs only and never borrower/credit/PII, free preview vs licence-gated full brief, and the hard constraint that an agent may relay the offer but can never complete a purchase. It also discloses the data vintage and method (CFPB HMDA 2025, actions 1-3, loan_type 2), the 'signals not findings' caveat, and attribution.

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

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

Front-loaded with the ANSWERS/PARAM structure so an agent gets triggers and input shape first, then constraints. It is dense and reads as one long run-on block, but virtually every clause carries load-bearing behavioral or licensing information rather than filler.

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

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

There is no output schema, yet the description enumerates the return payload (per-entity observed vs expected rates, coverage flags, method version, evidence-manifest hash) and covers licensing, PII limits, and epistemic caveats. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema description coverage is 100%, so each of the three parameters is already documented, including the 1-40 LEI cap and the explicit instruction to pass license_key only when the user provided it. The description's 'PARAM: a list of public LEIs' restates rather than extends that, so the baseline 3 applies.

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

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

States a specific verb and resource (screen a batch of counterparty LEIs against the public HMDA record) and names the exact output (observed vs expected FHA denial rates, coverage flags, method version, manifest hash). An agent can separate it from siblings like get_lender_denial_stats or screen_counterparties_quote 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 'ANSWERS:' clause gives concrete invocation triggers ('screen these LEIs', 'which counterparties deny more than predicted'), which is clear usage context. It does not, however, explicitly route the agent to alternatives (e.g. screen_counterparties_quote for pricing) or state when-not-to-use, so it falls short of the top band.

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 the safety profile is covered. The description adds real behavioral context beyond that: it does not execute the screen, and the figures are a historical observation from the CFPB HMDA 2025 record with stated filters, not a prediction.

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

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

Front-loaded with the ANSWER/PARAM structure, which is highly scannable. The trailing data-source, disclaimer, and attribution sentences are dense but arguably necessary compliance content rather than filler.

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

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

No output schema, but the description states what is returned (coverage and price) and its provenance, which is enough for an agent to call it correctly. Minor gap: no mention of response shape or whether all-or-nothing coverage reporting applies.

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 both parameters (lei_list range 1-40, license_key balance behavior) are already documented in the schema. The description restates 'a list of public LEIs' and adds little syntax or meaning beyond the structured field.

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 (quote cost/coverage for screening a list of LEIs) and explicitly scopes it as not running the screen, which cleanly separates it from the screen_counterparties sibling. The 'ANSWERS' framing maps directly to the user questions it resolves.

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

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

Explicitly says it is used before screen_counterparties so cost and coverage are known in advance, naming the alternative and the condition that selects it. That is a complete when-to-use statement.

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