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

Annotations already declare readOnly, idempotent and open-world behavior, so the safety profile is covered. The description adds real context beyond that: the upstream razorpay/ifsc dataset, caching that makes repeated calls cheap, and the shape of the success and error payloads. It stops short of richer disclosure such as refresh cadence or staleness of the cached data.

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?

Opening sentence is front-loaded and the routing guidance comes early, which is the right priority order. There is mild redundancy: return values are described twice (a detailed 'Returns ok: true with...' block and a second 'Returns:' line), which costs a little tightness.

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 an output schema present the description need not enumerate return fields, yet it still covers routing, data source, caching, error shape, and a worked example. Nothing an agent needs to select or invoke this correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already fully documented in the schema, which sets the baseline at 3. The description's Args section largely restates the schema (substring filter, omit for full list, 1-500 range) and adds little beyond the default-scaling note already present 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?

States a specific verb and resource ('look up the official 4-letter bank code ... or list banks by name') and immediately scopes what it is not ('this returns banks, not branches'). The HDFC -> HDFC mapping example makes the transform concrete and distinguishable from branch-oriented siblings.

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

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

Explicitly states when to use it ('before ifsc_lookup or search_branches when the user gave a bank name rather than a code') and names the alternatives for the opposite case ('use search_branches or ifsc_lookup for a specific branch'). Both the selection condition and the exclusions are spelled out.

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 cover the safety profile (readOnly, idempotent, openWorld), and the description adds real context beyond them: the key semantic that capabilities are reported for the *bank as a whole* rather than a branch, plus the specific failure modes (INVALID_INPUT for malformed code, NOT_FOUND for absent code). It stops short of noting dataset staleness or any rate limits.

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

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

Front-loaded with the core purpose and routing advice where they matter most. However, the return fields are listed twice (inline in the body and again under an explicit 'Returns:' block), and the Args/Returns/Example scaffolding duplicates information already given.

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 one-parameter read tool with an output schema and annotations, the description covers scope (bank-level, not branch-level), routing to the sibling, expected success payload, and error payloads. Nothing an agent needs in order to select or invoke it correctly is missing.

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

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

Schema description coverage is 100% and the sole parameter is fully documented in the schema, including length constraints and the uppercase behavior, so the baseline is 3. The description's `bank_code` note and "KKBK" example merely restate what the schema already says.

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

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

States a specific verb+resource ('Get bank-level facts for a 4-letter bank code') and enumerates the exact payload (type, MICR/IIN, payment-rail support). It explicitly differentiates itself from the sibling `bank_directory` by scope (capabilities/type vs name lookup).

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

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

Gives a direct routing rule in both directions: use this tool for capabilities or bank type, use `bank_directory` to go from a bank name to its code. That is an explicit when/when-not with a named alternative.

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

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

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered; the description adds the level-by-level traversal behavior (`bank_code` -> states, +`state` -> districts, +`district` -> branches) and notes truncation. This is meaningful added context beyond the annotations, though it is somewhat redundant with the separately documented 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?

Front-loads the purpose and the traversal model before args/returns, and each sentence carries weight. The Returns section duplicates what the output schema already provides, so it is slightly longer than strictly necessary.

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?

An output schema exists, so return values need no further explanation here. Between the description, schema, and annotations, an agent has everything needed to select and invoke this 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 every parameter is already documented, including the hierarchy semantics and the 'requires state' constraint. The description's Args section largely restates the same example values, adding little beyond the schema baseline.

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

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

The description states a specific verb and resource ('Discover the exact district and branch-name spellings') and explicitly names the sibling it complements ('search_branches'), so an agent can distinguish it without opening schemas.

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

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

It gives an explicit trigger condition ('Call this when a search returned nothing and you need to check spelling') and a rationale for preferring it over the alternative ('cheaper than guessing several more search calls'), effectively naming search_branches as the alternative path.

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

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the exact failure taxonomy (INVALID_INPUT, NOT_FOUND, three UPSTREAM_* variants) and the ok:true/ok:false shape. No rate limits or latency expectations, but this is strong added context.

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

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

Front-loaded with purpose and usage, then well-sectioned failure codes and an example that do real work. The 'Args:' and 'Returns:' blocks largely duplicate the input schema and the output schema, which is mild waste but far from bloat.

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 single-lookup tool with 100% schema coverage and an output schema already present, the description covers purpose, trigger, error taxonomy and return-field inventory. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the single parameter is fully documented there (format, case-insensitivity, whitespace trimming, not-a-bank-code). The description restates the same 11-character rule and example, adding no meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (retrieve) and resource (single bank branch) scoped by an identifier, and explicitly carves out uniqueness: 'the only tool that confirms a branch actually exists, and the only source of the branch's address, MICR, SWIFT/bic code...'. That contrast with ifsc_validate and the directory-style siblings is enough for an agent to route correctly without opening the schema.

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

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

'Use this whenever the user supplies an IFSC' gives a clear triggering condition. It does not name ifsc_validate or search_branches as the alternative or state when NOT to use this tool, so it falls short of explicit alternative routing.

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

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

Annotations already cover readOnly/idempotent/closed-world, but the description adds genuinely useful behavior beyond them: no network call, normalization of case/whitespace, the always-`ok: true` contract ('an invalid IFSC is a successful report, not an error'), and the enumerated stable `reason` codes. That is real operational context an agent cannot get from the annotations alone.

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

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

Front-loaded with the core purpose and the sibling tradeoff, then laid out in readable blocks. The Returns section partially restates what the declared output schema already provides, which is mild redundancy, but the Example is compact and instructive.

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 single-parameter, offline, idempotent validator, everything an agent needs is present: the layout rules, normalization behavior, empty-input handling, the success-vs-error contract, and the reason codes. An output schema exists, so return-value detail is a bonus rather than a gap.

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

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

Schema description coverage is 100% and the schema already documents normalization, emptiness, and maxLength, so the Args line ('The candidate string to validate') adds little. Baseline 3 applies since the schema does the heavy lifting; the description does not add format or syntax beyond it.

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

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

States a specific verb+resource ('Check whether a string is structurally a valid IFSC') and immediately scopes it as offline/no-network. It explicitly distinguishes itself from the sibling `ifsc_lookup` by naming it and stating the boundary (validation vs. branch existence).

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

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

Gives an explicit routing rule: 'Choose this over `ifsc_lookup` when you want to reject junk before spending a request', plus the when-not clause 'It does NOT confirm the branch exists - only `ifsc_lookup` does that.' Both the use case and the exclusion are stated, not implied.

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

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

Beyond the annotations (readOnly/idempotent/openWorld), the description discloses filter-combination semantics ('Filters are ANDed'), the rejection behavior and its error code (INVALID_INPUT with an unfiltered search), the reason (~170k rows, no list-all endpoint), and pagination fields (count, has_next). This is exactly the behavioral context annotations cannot carry.

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

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

Front-loaded with purpose, requirement and sibling routing before the details, which is good structure. However, the 'Args' and 'Returns' blocks substantially duplicate the 100%-coverage schema and the output schema, so some sentences do not fully earn their 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 six optional params, a rich output schema, and a need to disambiguate from bank_directory and branch_places, the description covers use case, preconditions, error behavior, return shape and a concrete example. An agent has everything needed to 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 coverage is 100%, so the baseline is 3; the description earns above that by adding cross-parameter meaning absent from the schema — that filters are ANDed and that at least one filter must be supplied. The per-argument list largely restates the schema, so it does not climb higher.

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

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

The first line states a specific verb (Find) and resource (bank branches) plus the exact situation that triggers it ('when you have a bank, city, state or branch name but no IFSC'). It also explicitly contrasts itself with the sibling bank_directory, so an agent can route correctly without opening any schema.

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

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

Names the alternative (bank_directory) and the condition that selects it ('Prefer this... when the user wants a branch; use bank_directory when they want a bank'), and states the hard precondition that at least one of bank_code/city/state/branch is required. Exclusions and alternatives are both explicit.

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