FDIC BankFind MCP Server

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

The description goes beyond the readOnly/idempotent annotations by explaining the proxy model nature, the omission of Management (M), the proxy metrics for Sensitivity (S), and the fact that this is not an official CAMELS rating. It also details the output structure, making the behavior fully transparent.

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

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

The description is well-structured, front-loaded with a clear summary, and uses bullets to organize output details. Every sentence adds value, and the note about limitations is essential. No wasted words.

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 tool is complex with a rich output schema, and the description covers the score scales, output components, and limitations comprehensively. The presence of an output schema reduces the need to explain return values, and the description effectively fills the remaining 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 description coverage is 100%, so the schema fully documents the parameters. The description adds no additional parameter-specific semantics beyond mentioning trend analysis over prior quarters, which is already captured by the 'quarters' parameter description. 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's function: 'Produce a CAMELS-style analytical assessment for a single FDIC-insured institution using the public off-site proxy model.' It identifies the specific verb, resource, and scope, and distinguishes it from siblings like fdic_analyze_credit_concentration by focusing on composite health.

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 this tool is for holistic CAMELS-style assessment but does not explicitly compare it to alternative sibling tools or state when to prefer this one. Sibling tools like fdic_analyze_funding_profile are more specialized. This is implied rather than explicit, so a score of 3 reflects the lack of direct 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?

The annotations already indicate this is a safe, read-only, idempotent operation. The description adds useful behavioral context: it computes CRE relative to capital, flags concentration risks, and returns structured JSON, while noting it's based on public financial data. This goes beyond annotations but doesn't cover edge-case behaviors.

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 and concise: a clear opening sentence, a bulleted output list, and a brief note. Each section adds information without redundancy, making it easy for an agent 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?

Given the analytical complexity and multiple outputs, the description provides a good high-level overview of what is computed and returned. Since an output schema exists, it doesn't need to detail every field, but it does list the main output categories and the regulatory basis, which is sufficient for an agent to decide when to use 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 description coverage is 100%, so the schema already documents both parameters (cert and repdte) with exactly the needed syntax and defaults. The description adds no additional parameter-specific semantics, so a baseline score of 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 analyzes loan portfolio composition and credit concentration risk for FDIC-insured institutions, with specifics like CRE concentration per 2006 interagency guidance. This distinguishes it from sibling analytical tools like funding profile or securities portfolio, which focus on other aspects.

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 through its focus on loan portfolio concentration, but does not explicitly state when to use it over alternatives or any exclusions. It provides context about the regulatory basis and data source, but lacks explicit 'when/when-not' 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, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds minimal extra behavioral context: it labels the tool as 'analytical' and states it uses 'public financial data'. It does not go beyond the annotations with details like rate limits or auth requirements, but there are none to disclose. The output list is also partially redundant with the existing 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 well-structured and efficient: a single opening sentence, a compact bulleted list of outputs, and a short note. It is front-loaded with the main purpose, and every sentence serves a purpose without redundancy. Length is appropriate 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?

For a read-only analytical tool with two simple parameters, strong annotations, and an existing output schema, the description provides sufficient context. It clearly enumerates what the user can expect from the output. The only gap is the lack of explicit tie-ins to sibling tools or when-not-to-use guidance, which prevents a perfect score.

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 coverage is 100%: both 'cert' and 'repdte' have clear descriptions (FDIC Certificate Number, Report date with pattern and default). The tool description does not add any parameter-level semantics beyond what the schema already provides. Per the rubric, baseline 3 is appropriate when schema covers parameters fully.

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's function: 'Analyze deposit composition, wholesale funding reliance, and funding risk for an FDIC-insured institution.' This is a specific verb+resource that distinguishes it from sibling tools covering other analytical areas like credit concentration or securities portfolio. The detailed output bullets further solidify the specific purpose.

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 establishes clear usage context by focusing on funding risk and deposit composition, which implies when to use this tool over alternatives. It does not explicitly name alternative tools or state exclusions, but the analytical scope is sufficiently unambiguous. The note about being an analytical tool based on public data adds a minor qualifier.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description need not repeat that. It adds valuable context by describing the output structure (securities relative to assets and capital, MBS concentration, AFS/HTM breakdown, risk signals, structured JSON) and explicitly notes that 'AFS/HTM breakdown is not currently available from the FDIC API.' This goes beyond the annotations and provides useful behavioral expectations, though it does not mention rate limits or error conditions.

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 a clear opening sentence, a bulleted list of outputs, and a concise note about data availability. Every element serves a purpose, and the formatting improves scannability. It is appropriately sized for the tool's analytical nature.

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 that an output schema exists, the description does not need to explain return values in prose. It covers what the tool does, what outputs to expect, and highlights a key limitation. This is complete for a tool with two parameters and good annotation support.

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 both parameters (cert and repdte), so the schema already documents them well. The description adds no extra parameter-level detail, but it does not need to. It maintains the baseline of 3, neither enhancing nor detracting from 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 clearly states the tool's purpose: 'Analyze securities portfolio size, composition, and concentration risk for an FDIC-insured institution.' This uses a specific verb and resource, and the focus on securities portfolio distinguishes it from sibling analysis tools like fdic_analyze_bank_health or fdic_analyze_credit_concentration.

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 securities portfolio analysis but does not explicitly specify when to use this tool versus alternatives or provide exclusion criteria. While the context is clear, there is no direct guidance such as 'use this when analyzing MBS concentration' or 'for credit concentration, use fdic_analyze_credit_concentration instead.' This is implied rather than stated, matching a score of 3.

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 description discloses non-obvious internal behavior: it 'batches institution roster lookup, financial snapshots, optional office-count snapshots, and can also fetch a quarterly time series inside the server.' It also describes the return content (text, deltas, metrics, insight tags). Since annotations already cover read-only/idempotent safety, the description adds meaningful behavioral context without 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 well-structured and front-loaded with a clear summary, followed by use cases, input explanations, and return details. It is longer than minimal, but the extra length serves a complex 11-parameter tool and helps orient the agent quickly.

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 of this complexity with an output schema and comprehensive annotations, the description covers the main behaviors, input choices, and output summary. Minor gaps remain (e.g., what happens if neither state nor certs is supplied), but overall it gives an agent enough context to use 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 description coverage is 100%, so a baseline of 3 applies. The description adds semantic value by explaining that 'state or certs' are alternative ways to define the comparison set, and it clarifies the meaning of analysis_mode and include_demographics beyond the schema's dry 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 clearly states the tool's function: 'Compare FDIC reporting snapshots across a set of institutions and rank the results by growth, profitability, or efficiency changes.' This provides a specific verb, resource, and scope, and the 'Good uses' examples further distinguish this tool from siblings like fdic_fetch or fdic_search.

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 positions the tool for 'heavier analytical prompts that would otherwise require many separate MCP calls' and lists several 'Good uses.' This gives strong when-to-use guidance, though it does not explicitly name alternative tools or mention 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 establish read-only/idempotent safety, and the description adds substantial behavioral context: auto-peer selection broadens the cohort when fewer than 10 peers match, peer_context.subject_percentiles is deprecated, and the output is an analytical proxy rather than official supervisory ratings.

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

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

Well-structured with clear sections for purpose, usage modes, and output details. Although detailed, every sentence earns its place, including the deprecation warning and proxy disclaimer.

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 usage modes, output fields, auto-peer fallback, deprecation, and the non-official caveat. Since an output schema exists, it doesn't need to repeat return types, and the extra guidance on metrics vs proxy_summary is valuable for correct UI bindings.

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 already covers 100% of parameters, providing baseline 3. The description goes beyond by grouping parameters into usage modes (certs, state, asset range) and clarifying that cert highlights a subject institution, which adds semantic meaning beyond individual field 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?

Clearly states the tool compares CAMELS-style health scores across FDIC-insured institutions. The three usage modes (explicit certs, state-wide, asset-based) define the exact scope and distinguish it from sibling tools like fdic_peer_group_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 context for when to use the tool by naming three concrete usage modes and an optional subject-cert parameter. It does not explicitly name alternatives or state when not to use it, so it stops short of full when-not 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?

With readOnlyHint=true and destructiveHint=false already in annotations, the description adds meaningful context by explaining the proxy engine, standardized severity levels, and that the output is 'signal-shaped, not assessment-shaped.' It also discloses the tool is a 'public off-site analytical proxy — not official supervisory ratings,' which is valuable beyond what annotations convey.

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 sections: purpose, signal codes with severity, scan modes, output description, and a caveat. It is front-loaded with the main purpose, and every section is informative without redundancy. The use of bullet lists and short labeled lines keeps it scannable.

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 is quite complete given the output schema exists and covers return values. It includes signal code lists, severity semantics, scan modes, and a critical caveat. However, it does not specify what happens if no scan mode parameters are provided (all parameters are optional), nor does it clarify precedence when multiple modes are combined. This is a minor gap for a tool with zero required parameters.

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 baseline is 3. The description adds semantic structure beyond the schema by grouping parameters into three scan modes (state, certs, asset_min/asset_max) and linking min_severity to the listed severity levels. This helps the agent understand how to combine parameters, which is not explicit 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 clear verb+resource: 'Scan FDIC-insured institutions for early warning risk signals using the public_camels_proxy_v1 analytical engine.' It explicitly distinguishes from analytical siblings by stating the output is 'signal-shaped, not assessment-shaped' and emphasizes the early-warning nature, which sets it apart from fdic_analyze_bank_health and similar 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 description provides clear usage context by listing three scan modes (state-wide, explicit CERT list, asset-based) and describing the corresponding parameters. It also states the output shape and the caveat about being a public proxy, but it does not explicitly mention when not to use this tool or name alternative tools, 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, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds the behavior that the tool retrieves 'full citation text' and accepts various id formats, but it does not disclose edge-case behaviors (e.g., invalid id handling, response format beyond what output schema provides). This is acceptable but not rich.

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, front-loaded with the usage instruction, then provides concrete examples. Every word earns its place, with no redundancy or fluff.

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 simple one-parameter tool with rich annotations (readOnly, idempotent, non-destructive) and an output schema present, the description fully covers when to use it and how to invoke it. The output schema handles return-value details, so no further explanation is needed.

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 100% coverage of the single 'id' parameter, including its description with format examples. The tool description repeats these same examples without adding new semantic meaning. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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 ('fetch') and resource ('FDIC BankFind Result' as 'full citation text for a result returned by search'). It distinguishes this from sibling tools by implying it is the post-search retrieval step, and provides concrete id format examples (e.g., 'institution:3511', 'schema:institutions'), which eliminate ambiguity.

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

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

The description opens with 'Use this when the model needs the full citation text for a result returned by search,' which is an explicit usage context. It gives example id formats as guidance, but it does not explicitly contrast with sibling tools like fdic_get_institution, making the alternative boundary slightly implicit.

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 the tool read-only, idempotent, and non-destructive. Beyond that, the description adds valuable behavioral detail: it uses SOD data, groups non-MSA branches under 'Non-MSA / Rural', sorts markets by deposits, and includes summary counts. This significantly exceeds what annotations alone provide.

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

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

The description is well-structured with a leading purpose sentence, a bulleted output list, and a closing note about rural branches. It is concise, scannable, and every line contributes meaningful information without 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 context signals include an output schema and helpful annotations, the description still provides essential additional context: data source, grouping behavior, sorting, and output categories. It fully covers the tool's behavioral scope for an agent to select and invoke 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 description coverage is 100%; both 'cert' and 'year' are described in the schema itself. The description does not add parameter-level meaning beyond restating that the data is SOD-based, so it stays at the baseline for full schema coverage.

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 ('Analyze') and a precise resource ('geographic franchise footprint ... using Summary of Deposits (SOD) data'). It clarifies the output as a market-by-market breakdown of branches, deposits, and percentages, which distinguishes it from sibling tools like fdic_market_share_analysis or fdic_get_institution.

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—when you need to see an institution's geographic footprint and deposit distribution across MSAs—but it does not explicitly state when to use this tool over alternatives or mention any exclusions. Clear context is present, but there is no direct comparison or 'use when...' 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 the tool as read-only, idempotent, non-destructive, and closed-world, so the description need not repeat these. The description adds a small behavioral insight: it returns 'one institution profile' (a single record lookup) and emphasizes 'exact' certificate number, implying no fuzzy matching. However, it does not go beyond that, so it only adds marginal value over 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 two concise sentences with no filler. It front-loads the primary use case, then the alternative for discovery. Every word 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?

For a simple two-parameter read tool with an output schema and comprehensive annotations, the description fully covers what an agent needs: the exact input condition, the output nature (one profile), and how to find the cert if unknown. No significant gaps remain.

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 both parameters (cert, fields) already documented. The description reinforces that cert is the unique identifier and requires an 'exact' match, but it does not add new syntax or format details beyond the schema. Baseline 3 is appropriate since the schema carries the full burden.

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's function: 'Get Institution by Certificate Number' with a specific verb ('get') and resource ('institution profile'). It explicitly distinguishes from siblings by specifying the condition 'when the user knows an exact FDIC Certificate Number' and contrasts with search tools like fdic_search_institutions and fdic_search.

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

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

The description provides explicit usage guidance: use when the user knows an exact CERT number and needs one profile. It also gives a direct alternative for discovery ('To discover a CERT first, call fdic_search_institutions or fdic_search'). This fully covers when-to-use and 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 declare read-only and idempotent behavior. The description adds valuable non-obvious behavior: it responds with `found: false` for non-failed institutions, which clarifies edge-case handling beyond what annotations provide.

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

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

The description is two sentences, front-loaded with the usage condition and followed by return behavior. No wasted words, and every sentence adds 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's simplicity, an output schema exists, and annotations cover safety, the description is complete enough. It explains the core use case and the not-found behavior, which are the main contextual 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%, so the baseline is 3. The description mentions 'CERT' and 'failure record' but does not add significant meaning beyond the schema's existing parameter descriptions for `cert` and `fields`.

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's purpose: retrieving a specific failure record for a known CERT. It distinguishes from siblings like fdic_get_institution (general institution data) and fdic_search_failures (search across failures) by focusing on the direct lookup use case.

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 it: 'when the user knows the CERT of a failed institution and needs its specific failure record.' It also implies when not to use it (if the institution did not fail) but does not name alternative tools or provide 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 establish read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: it is an analytical tool based on public financial data, and it explicitly lists output components (consolidated summary, subsidiary list, structured JSON). This goes beyond mere restatement of annotations without contradicting them.

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

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

The description is concise, front-loaded with the action, and well-structured with bullet points for output. Every sentence adds value, and the note about analytical nature is brief. No wasted words.

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 2 optional parameters and an output schema, the description is largely complete. It explains purpose, input options, output structure, and the nature of the data. A minor gap is the behavior when neither parameter is provided, but this is a minor edge case given the schema's explicit descriptions and the output schema's presence.

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 parameter already explained in detail (e.g., cert description says it looks up the holding company). The description reinforces these semantics but does not add new information beyond the schema. Baseline 3 is appropriate given the schema does the heavy lifting.

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 profiles a bank holding company by grouping FDIC-insured subsidiaries and aggregating financial metrics. It specifies two lookup methods (holding company name or subsidiary CERT), which distinguishes it from siblings like fdic_get_institution and fdic_search.

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 for when to use the tool: to profile a holding company or find a subsidiary's parent. It does not explicitly exclude alternatives or mention when not to use it, but the analytical purpose is well implied. The sibling list shows many specialized tools, and this one's role is distinct enough to be easily selected.

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, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral context: it computes market share, ranks institutions, calculates HHI per DOJ/FTC guidelines, and produces a structured output with overview, optional highlight, top institutions, and JSON. 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 well-organized and front-loaded: the opening sentence states the purpose, followed by labeled entry modes, output bullets, and a closing requirement. Every section earns its place, and there is no redundant filler. Despite its length, the structure makes it easy to scan.

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

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

For a tool with 5 parameters and two operation modes, the description fully covers both modes, required arguments, optional cert highlighting, output components, and even references a sibling tool for configuration. Given the schema and output schema already exist, this description leaves no major gaps in understanding how to select and invoke the tool.

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

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

Input schema has 100% documentation coverage, so the baseline is 3. The description adds meaning by clarifying the 'at least one of' selection logic and the city+state dependency, which are not fully captured by individual schema properties. It also provides concrete examples like '19100' and 'TX', though these also appear in the schema, so the added value is moderate.

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 opens with a specific verb+resource: 'Analyze deposit market share and concentration for an MSA or city market using FDIC Summary of Deposits (SOD) data.' It clearly distinguishes from sibling tools by focusing on market share ranking and HHI analysis rather than raw data retrieval or other financial health analyses.

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 describes two entry modes (MSA vs city+state), states the minimum requirement ('Requires at least one of: msa, or city + state'), and directs users to fdic_search_sod for MSABR lookups. This provides clear when-to-use guidance and even references a sibling tool for configuration.

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; the description adds key behavioral details: competition rank (1,2,2,4), the comparison set includes matched peers plus subject, limit does not affect ranking, and override precedence. This goes well beyond annotation-only 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 compact but structured: purpose, usage modes, metric list, ranking methodology, output contents, override precedence. No redundant sentences; each line earns 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 10 optional parameters and rich schema/annotations/output schema, this description covers usage modes, methodology, output contents, and parameter interactions. It even references a sibling for next steps. 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 covers 100% of parameters with descriptions, so the baseline is 3. The description contributes a unifying usage-mode framework (subject-derived vs explicit criteria) and override precedence that explains how parameters interact, which is not directly in schema. However, many defaults are already in parameter descriptions, so it doesn't reach 5.

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

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

The description opens with a specific action: 'Build a peer group for an FDIC-insured institution and rank it against peers on financial and efficiency metrics at a single report date.' This clearly distinguishes it from trend analysis tools and other FDIC analysis tools by emphasizing peer group ranking at a single date.

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 lists three usage modes (subject-driven, explicit criteria, subject with overrides) and states when to use each. It also names a sibling tool for trend analysis ('pass to fdic_compare_bank_snapshots'), fulfilling the when/alternative 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, and non-destructive behavior. The description adds valuable context by specifying the data source ('public BankFind quarterly financials'), the scope ('executive snapshot metrics, trend series, community-bank comparison data'), and explicit exclusions ('non-public or non-BankFind QBP items'). This goes beyond the safety profile and clarifies what the tool will and will not include, though it does not detail internal processes or error 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?

Two sentences, highly efficient. The first sentence front-loads the main purpose, and the second succinctly enumerates the inclusions and exclusions. No filler or redundant phrasing—every clause carries meaningful 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?

Given the tool has only three optional params, a clear read-only/idempotent annotation profile, and an output schema (as per context), the description covers the essential aspects: what is built, its contents, and its constraints. It doesn't mention fallback behavior for missing repdte (though the schema does) or output structure (covered by output schema), leaving only minor gaps such as detail on how exclusions are determined. Overall adequate for a straightforward data generation 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 100% with descriptive parameter docs, so baseline is 3. The description adds some semantic connection by mentioning 'trend series' (aligns with trend_quarters) and 'community-bank comparison data' (aligns with include_community_banks), but it does not add new syntax or format details beyond the schema. It reinforces the mapping but doesn't significantly enhance parameter understanding.

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's purpose with a specific verb ('Build') and resource ('chart-ready data for a concise QBP Lite report') and adds scope details ('from reproducible public BankFind quarterly financials'). It also lists included components and exclusions, distinguishing it from sibling analysis/search tools which focus on insights rather than generating a data bundle.

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 by defining the output type (chart-ready data for QBP Lite), but it does not explicitly state when to prefer this tool over alternatives or provide exclusionary guidance. No sibling tools are mentioned, so the user must infer from the specific report scope that this is for generating a bundle rather than analyzing or fetching single records.

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 readOnly/idempotent annotations, the description discloses graceful degradation when FRED is unavailable, the API key dependency, and that it produces both narrative and structured JSON output. This provides valuable behavioral context not covered by 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 with a clear opening sentence, a concise output list, and a crucial note about FRED_API_KEY. Every sentence contributes useful information with no redundancy, and the most important purpose 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?

Given the presence of a rich output schema and strong annotations, the description covers the essential additional context: purpose, data source, outputs, degradation behavior, and environment requirement. It is sufficiently complete for a tool with three optional parameters.

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% with parameter descriptions already provided. The description adds some context by naming the data sources (FRED) and outputs (state/national unemployment, federal funds rate), but doesn't deeply elaborate on how each parameter maps to those outputs, so 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 overlays macroeconomic/regional data on a bank's geographic context using FRED, with specific indicators (state/national unemployment, federal funds rate). This verb+resource+scope clearly distinguishes it from siblings like fdic_analyze_bank_health or fdic_franchise_footprint.

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 use for bank performance assessment when macro context is needed, and explicitly mentions the FRED API key requirement. However, it doesn't name alternatives or state when not to use this tool explicitly, so it misses the full 'when/when-not' 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, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds behavioral context by stating 'Returns up to 8 results with id, title, and source URL,' which is useful beyond annotations. 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 two sentences, front-loaded with the usage instruction, and contains no redundant or irrelevant information. Every sentence contributes to understanding the tool's purpose, usage, and output.

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 simple tool with one parameter, rich annotations, and an output schema, the description is complete. It includes the result limit ('up to 8 results') and the fields returned, which are key behavioral details. No significant gaps exist.

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 100% coverage for the single 'query' parameter with description 'Natural-language search query.' The tool description adds potential search targets ('institutions, failed banks, branches, or schema documentation') but does not provide additional parameter syntax or format details. Baseline 3 applies due to high schema coverage.

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's purpose: 'Use this when the model needs citation-friendly FDIC BankFind search results for institutions, failed banks, branches, or schema documentation.' It uses a specific verb ('search') and resource ('FDIC BankFind'), and distinguishes itself from sibling tools by covering multiple entity types in a general search.

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 starts with 'Use this when...' providing a direct usage condition for when to invoke the tool. However, it does not mention alternatives or when not to use it, such as pointing to specialized sibling tools like fdic_search_institutions or fdic_search_failures. The clear usage context earns a 4.

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, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds useful context about the nature of the data (quarterly, demographic, market-structure) and points to a schema for the full field catalog, enriching the behavioral picture 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 just two sentences, front-loaded with the primary use case, followed by key filter guidance and a pointer to the full schema. Every sentence earns its place with no wasted wording.

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 a complete schema (100% coverage), an output schema present, and annotations covering safety, the description provides sufficient context for a search tool. It specifies the data type, how to filter, and directs users to the full field catalog, making it complete for its complexity.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters well. The description adds a minor hint about filtering by CERT and/or REPDTE but does not materially improve parameter understanding. Baseline 3 is appropriate when the schema handles the heavy lifting.

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 quarterly demographic and market-structure attributes with specific examples (office counts, metro classification, county/territory codes) for FDIC-insured institutions. The verb 'search' plus the resource 'demographics data' distinguishes it from sibling tools that focus on financials, institutions, locations, or history.

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 guidance on when to use the tool ('Use this when the user wants quarterly demographic and market-structure attributes'). It also suggests key filters (CERT and/or REPDTE), but does not mention alternative tools or when not to use it, which would make it 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, idempotentHint=true, and destructiveHint=false, so the core safety profile is known. The description adds that the operation returns failure records with pagination and points to a field catalog, which provides useful behavioral context beyond the annotations without contradicting them.

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

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

The description is two sentences: the first states the primary purpose and filter options, the second describes the return behavior and schema reference. Every sentence earns its place, with no repetition or padded wording. It is front-loaded and appropriately sized.

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 detailed input schema, output schema, and rich annotations, the description adequately covers the core scenario (searching failed institutions with filters) and references the full field catalog. It doesn't explicitly mention how this differs from fdic_search_institutions, but the 'failed' qualifier makes the focus clear. Slight room for improvement in explicitly addressing pagination defaults.

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 all six parameters thoroughly explained in the schema—including examples and syntax. The description adds only high-level filter categories (name, state, date range, etc.), which are helpful but not mapped directly to parameter names. This aligns with the baseline of 3 when the schema carries the parameter documentation burden.

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

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

The description uses a specific verb ('search') and a specific resource ('failed FDIC-insured institutions'), and it clearly distinguishes this from sibling tools by focusing on failures. It also lists the filter dimensions (name, state, date range, resolution type, cost), making the tool's 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?

The description explicitly opens with 'Use this when the user wants details on failed FDIC-insured institutions filtered by...', providing clear context for when to invoke this tool. However, it does not mention when not to use it or point to alternative sibling tools (e.g., fdic_get_institution_failure for a single failure), so it stops short of full 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's job is lighter. It adds useful context by specifying the data domain (quarterly Call Report data) and referencing the full field catalog. It doesn't contradict annotations, and no additional safety disclosure is needed given the optimistic 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 sentences, front-loaded with the primary use case, followed by filtering guidance and a reference to the schema catalog. Every sentence provides distinct value with no redundancy or fluff.

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

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

For a complex tool with 1,100+ fields and an existing output schema, the description effectively covers the core purpose, key filters, and points to the schema for full field details. It doesn't need to explain return values since an output schema exists, and the description is sufficiently complete for an 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?

Schema description coverage is 100%, so the baseline is 3. The description adds a brief mention of 'Filter by CERT and/or REPDTE plus optional ElasticSearch filters,' which orients the user but doesn't provide additional syntax or meaning beyond the schema's already detailed parameter 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 clearly states the tool provides quarterly Call Report data (balance sheet, income, capital, performance ratios) for FDIC-insured institutions, using a specific verb ('wants') and resource. It distinguishes from siblings by focusing on financial data and explicitly mentions filtering by CERT and REPDTE, unlike institution-centric or demographic search 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 description opens with 'Use this when the user wants quarterly Call Report data,' giving clear when-to-use guidance. It also explains how to filter via CERT/REPDTE and optional ElasticSearch filters, but it does not explicitly name alternatives or when-not-to-use conditions, so it stops 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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by specifying the scope (structural changes) and the available filter dimensions, which helps set expectations. It does not describe pagination or rate limits, but that is less critical given 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 two sentences. The first sentence front-loads the use case and filterable attributes; the second efficiently points to the full field catalog. There is zero wasted text.

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 is sufficient for the tool's complexity. It covers purpose, key filter options, and provides a pointer to the field catalog. With a rich input schema, output schema, and annotations, nothing essential is missing 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?

All 7 parameters have detailed descriptions in the schema (100% coverage), so the baseline is 3. The description mentions filter dimensions (CERT, type, change code, date range, state) but does not explain how to construct them beyond the schema's 'filters' parameter description. The added value is minimal.

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 explicitly states the tool is for retrieving structural-change events (mergers, acquisitions, name changes, charter conversions, failures) for FDIC-insured institutions. This clearly distinguishes it from sibling tools like fdic_search_failures (which focuses only on failures) and fdic_search_institutions (which covers general institution data).

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 a clear when-to-use statement: 'Use this when the user wants structural-change events'. It also lists applicable filters (CERT, type, change code, date range, state) and references a schema for more detail. However, it does not explicitly state when NOT to use it or name alternative tools, so it lacks full exclusion/alternative 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?

The annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by disclosing that results are institution profile rows with pagination, and it directs to a field catalog via fdic://schemas/institutions. 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?

Two sentences with no filler. The purpose is front-loaded, followed by return type and a pointer to the field catalog. Every sentence 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?

Given the output schema exists and annotations cover safety, the description effectively covers the tool's purpose, pagination behavior, and points to the full field catalog for complete parameter understanding. The search criteria mentioned align with the filterable fields.

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

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

With 100% schema description coverage, the baseline is 3. The description does not add parameter-specific detail, but the schema thoroughly documents each parameter with examples and defaults. The description's mention of search criteria maps to the filters parameter but does not enhance beyond 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 'Use this when the user needs FDIC-insured institution search results' and enumerates specific search criteria (name, state, CERT, asset size, charter class, regulatory status). This clearly specifies the verb+resource+scope and distinguishes it from sibling tools like fdic_get_institution (likely single-record) and fdic_search_financials.

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 trigger conditions ('Use this when...') and notes pagination and the schema reference. However, it does not explicitly mention alternatives or when not to use this tool, 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by stating what the tool returns (address, coordinates, branch number, service-type rows) and referring to a schema for the full field catalog, providing useful behavioral context 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 two sentences, front-loaded with usage context, and contains no filler. Every sentence contributes: the first specifies when to use and filter dimensions; the second details return types and points to a schema for more detail.

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 tool is a search/lookup operation with 7 parameters, an output schema, and good annotations. The description covers purpose, return types, and schema reference. It doesn't mention pagination or caveats, but the schema covers those, making the description sufficiently complete for an 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 description coverage is 100%, so the baseline is 3. The description adds semantic value by naming filter dimensions (CERT, state, city, county, metro area, branch type) that are not all explicitly listed in the schema's common fields, helping the agent construct filter expressions.

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's purpose: retrieving branch/office locations for FDIC-insured institutions with specific filter dimensions (CERT, state, city, county, metro area, branch type). It distinguishes from sibling search tools by focusing on locations/branches and listing return types (address, coordinates, branch number, service-type rows).

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 begins with 'Use this when the user wants branch/office locations...' which is an explicit usage context. It does not explicitly mention when not to use or name alternatives, but the purpose is narrow enough to differentiate from sibling search tools like fdic_search_institutions or fdic_search_financials.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safe, read-only nature is clear. The description adds temporal context (as of June 30 each year) and data granularity (branch-level), which goes beyond annotations. It doesn't detail response shape, but an 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?

Two sentences are concise and front-loaded. The first sentence gives the use case, and the second covers filtering and a pointer to the full field catalog. Every word 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?

Given 8 parameters, a complete input schema, and an output schema, the description provides the essential when-to-use context and data vintage. It also references fdic://schemas/sod for field catalog details, covering potential gaps. It lacks a note about pagination limits or offset, but those are already in the 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?

All 8 parameters have rich descriptions in the input schema (100% coverage), so the baseline is 3. The description only restates 'Filter by CERT and/or year' and references fdic://schemas/sod for field names, adding no new parameter-level meaning 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 clearly states the tool's function: 'annual branch-level deposit data (SOD, as of June 30 each year) — branch deposits, MSAs, geographic distribution'. It identifies the resource (Summary of Deposits) and the scope (branch-level, annual), distinguishing it from sibling search tools that cover financials, institutions, or locations.

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 begins with 'Use this when the user wants annual branch-level deposit data', providing explicit context for when to use. It also mentions filtering by CERT and/or year, but does not explicitly state when not to use or name alternative tools, so it loses one point for missing 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, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds the annual snapshot nature and field scope, but doesn't disclose additional behavioral traits such as pagination behavior or response structure, which are partly covered by schema and output schema. 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 exceptionally concise: two sentences that front-load the primary use case and then direct the user to a schemata reference for the full field catalog. Every word earns its place, with no redundancy or 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?

Given the tool's moderate complexity (8 parameters, output schema, rich annotations), the description provides the necessary high-level purpose and usage context while relying on the schema for details. However, it could be more complete by explicitly naming sibling alternatives to help disambiguate among the many FDIC search tools.

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 provides 100% coverage with detailed descriptions for all 8 parameters, including types, ranges, defaults, and examples. The description adds minimal extra meaning beyond stating CERT/year filtering and a few summary fields, so it doesn't meaningfully augment what the schema already communicates.

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 providing annual financial-summary snapshots (assets, deposits, ROA, ROE, offices) for FDIC-insured institutions, with filtering by CERT and/or year. This specific verb-resource-scope combination distinguishes it from sibling search tools like fdic_search_financials or fdic_search_institutions.

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 opening phrase 'Use this when the user wants annual financial-summary snapshots' provides explicit when-to-use guidance. However, it does not mention when not to use it or contrast it with specific alternatives among the many sibling search tools, so it slightly misses the full 5-point criterion.

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 read-only and idempotent behavior. The description adds behavioral context about output format (interactive widget vs Markdown table) and content scope, which is useful beyond the structured 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?

Two sentences, front-loaded with usage guidance, no filler. Every word 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?

Given the high schema/annotation coverage and output schema presence, the description provides sufficient context for an agent to select and invoke the tool. It covers content, rendering, and default behavior.

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 with descriptions for both cert and repdte. The description adds no additional parameter-level detail but the schema is sufficient.

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 produces a scannable single-institution dashboard containing identity, public financial metrics, risk signals, and source links. This distinguishes it from sibling tools like fdic_get_institution or fdic_detect_risk_signals, which focus on raw data or specific signal detection.

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 ('Use this when the user wants a scannable single-institution dashboard') and notes rendering differences across clients. It does not explicitly list when not to use or name alternative tools, but the context is clear.

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, and non-destructive behavior. The description adds valuable context beyond those: ratios are computed from Call Report data, are 'UBPR-equivalent, not official FFIEC UBPR output', and the tool is analytical based on public data. This clarifies the nature of results 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 well-structured with a clear lead sentence, a bulleted list of output categories, and a brief note. Every section earns its place by informing the agent about scope, outputs, and data provenance. It is appropriately sized for a complex analysis tool and front-loads the main purpose.

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 tool is a multi-faceted analytical tool, and the description covers all major output areas (summary, mix, capital, liquidity, growth) and mentions the output format (structured JSON). The caveat about non-official UBPR adds important context. Given that an output schema exists, the description does not need to detail return fields. It is complete for the 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema; it mentions the report date default and the institution certificate implicitly but does not explain how parameters affect the analysis. It provides no extra syntax or format details. Thus it meets but does not exceed the schema's contribution.

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: 'Compute UBPR-equivalent ratio analysis for an FDIC-insured institution.' It enumerates distinct output categories (summary ratios, loan mix, capital adequacy, liquidity, growth), clearly distinguishing this from sibling tools focused on other analyses like bank health, credit concentration, or funding 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?

While no explicit 'use when' or alternative tools are named, the description clearly implies usage context: any time UBPR-equivalent ratio analysis is needed, including specific ratio categories. It also notes the non-official FFIEC status, which sets expectations. No exclusions or alternative recommendations are present, but the scope is sufficiently clear.

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, openWorldHint, idempotentHint, and destructiveHint false, covering safety. The description adds that the tool returns 'full citation text' and includes id format examples. It does not delve into error behavior or the exact nature of the citation text, but with annotations the bar is met.

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 a single, front-loaded sentence that directly states usage and gives concrete examples. No unnecessary words or repetition.

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 one simple parameter, a rich output schema, and strong annotations, the description sufficiently covers usage. It could mention error handling for invalid IDs, but the output schema and annotations fill most gaps. The description is complete for a straightforward fetch 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 100% since the schema describes the single 'id' parameter with examples. The description repeats similar examples ('institution:3511', etc.) without adding new meaning. 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 'full citation text' for a search result by ID, with a specific verb and resource. It distinguishes from sibling search/analysis tools by focusing on fetching a specific result. The title reinforces the purpose.

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 opens with 'Use this when the model needs the full citation text for a result returned by search,' giving clear when-to-use context. It provides the input format and examples. It does not explicitly name alternatives, but the context is sufficient.

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 tool as read-only, idempotent, and non-destructive, so the description doesn't need to repeat safety traits. It adds behavioral context by stating that the search returns up to 8 results and includes specific fields (id, title, source URL), which is useful beyond the annotations. No contradiction with annotations is present.

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

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

The description is concise and front-loaded, with two sentences that directly state the usage context and result format. Every sentence earns its place—the first tells when to use, the second tells what to expect. There is no fluff or redundant 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?

For a simple one-parameter search tool with an output schema present, the description provides sufficient context: it names the resource, the return limit, and the fields. It doesn't need to explain return values in detail because the output schema exists. It could slightly improve by referencing the specific sibling alternatives, but overall it's complete for the tool's complexity.

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 already fully describes the single 'query' parameter as a natural-language search query (100% coverage). The description does not add any additional meaning to the parameter itself; it only describes the output. Since schema coverage is high, a baseline score of 3 is appropriate even without extra param info.

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 that the tool searches FDIC BankFind and returns up to 8 results with id, title, and source URL. It identifies the resource (FDIC BankFind) and the action (search), and specifies the scope (institutions, failed banks, branches, schema documentation). However, it doesn't explicitly differentiate from sibling search tools like fdic_search_institutions or fdic_search_failures, so it's clear but not fully distinct.

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 begins with 'Use this when the model needs citation-friendly FDIC BankFind search results,' which provides a clear usage context. It also implies suitability for citation purposes. However, it does not mention when to use alternative search tools or when not to use this one, falling short of the 'explicit when/when-not/alternatives' bar for a 5.

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