BondTerminal

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: billing at 1 calculation unit per bond, a 50-bond per call limit, OAS model assumptions when a curve exists, and the annual-basis EUR spread convention. It omits auth requirements and settlement-date defaulting, keeping it short of a 5.

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

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

Dense but nearly every clause carries load: conventions, limits, billing, and the EUR carve-out are all decision-relevant. The opening sentence about OAS output is slightly redundant given an output schema exists, and the action statement ('Run what-if bond analytics...') would be stronger front-loaded, but nothing is padding.

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 calculation tool with an output schema and full annotations, the description covers conventions, cardinality limits, cost, and the one-of-four input rule. The only material omission is the settlement date parameter's behavior, including what happens when it is omitted.

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?

Despite low schema description coverage, the description supplies the semantics that matter: YTM is percent S.A. for every bond, spreads are basis points on the same basis with a documented EUR exception, and prices are per 100 face. The mutually-exclusive 'exactly one input' constraint is stated here and nowhere in the schema. The settlement parameter is left unexplained, which is the main gap.

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: run what-if bond analytics computing yield or price from one of four supplied inputs per bond. This is clearly distinct from the sibling retrieval tools (search_bonds, get_history, treasury_curve) which fetch rather than calculate. An agent can pick this tool without inspecting 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?

It gives the key selection rule: supply exactly one of price, YTM, G-spread, or Z-spread per bond. It also sets the 50-bond cap and explains the EUR/Bund spread basis exception. It does not explicitly name when to prefer a sibling retrieval tool, but the calculate-vs-fetch split is unambiguous.

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 read-only, idempotent annotations, the description discloses important behavior: identifier aliasing for Argentine sovereigns, the default cable USD pricing lane, quoteBasis reporting, YTM and spread conventions, deprecated oas behavior, response format default, and billing units. These are substantive operational details that help an agent invoke the tool correctly.

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 contains useful information but is dense and front-loads a niche detail about optionAdjustedSpread and oasStatus before the main purpose. The yield and spread conventions are valuable but packed into long, jargon-heavy sentences that reduce readability.

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 financial tool with 0% schema coverage, the description provides substantial context: identifier semantics, pricing lane behavior, yield conventions, spread basis, response format default, and billing. Settlement date semantics and explicit include enum meanings are the main gaps, though the output schema reduces the need to describe return values.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains identifiers well, including accepted formats and the 10-bond cap, and indirectly maps include to reference, analytics, and cashflows. It does not explain the settlement date parameter or the difference between concise and detailed response formats in detail.

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 core action: resolve and compare reference data, live analytics, and optional cashflows for up to 10 bonds. It adds detail about identifier types and batch behavior, though it does not explicitly distinguish the tool from siblings like search_bonds or calculate.

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 implied usage guidance by saying to send up to 10 identifiers per call instead of one search per issuer, which points toward batch retrieval. However, it does not explicitly state when to use this tool versus bondterminal_search_bonds, bondterminal_calculate, or bondterminal_get_history.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantive context beyond them: response capped at 750 points, explicit ranges capped at 730 days, and 10 read units per call billing cost. It also discloses data conventions (S.A. basis, EUR spreads over Bund on annual basis), which an agent needs to interpret results correctly.

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 core purpose is front-loaded in the first sentence, and the remaining clauses on yield basis, caps, and billing each add needed information. The EUR-exception sentence is dense and parenthesis-heavy, but nothing is redundant.

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

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

With an output schema present, return values need no explanation, and the description covers range caps, point caps, billing, and yield conventions. What's missing is identifier format and date-boundary semantics — the two things most likely to cause a failed call.

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

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

Schema coverage is 0%, so the description must carry the load; it clarifies that range is a 'named range' alternative to explicit start/end, and defines units for the returned fields. However it never states what an identifier accepts (ISIN/CUSIP/ticker), whether start/end are inclusive, or precedence when range and dates are both supplied — significant gaps for a required parameter.

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?

Specific verb plus resource: 'Return daily price, YTM, YTW, and spread history for one bond.' An agent immediately knows this is a time-series tool, which implicitly separates it from snapshot siblings like get_bonds or get_terms. It never names or contrasts a sibling explicitly, so it stops short of a 5.

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 explains the two input modes ('using a named range or explicit dates') and the 730-day cap, which is real usage guidance for parameters. But there is no explicit when-to-use / when-not-to-use statement versus siblings such as treasury_curve or get_bonds, leaving tool selection to inference.

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

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

Goes well beyond the readOnly/idempotent annotations: billing units (5 read units per bond), hard limits (10 bonds per call, 60 distinct term sheets/day per account), and the critical semantics that non-confirmed states (not_confirmed/not_found/does_not_apply/not_read) 'never mean no'. That last point is essential to avoid misinterpreting results.

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 scope and constraints, and every sentence carries information (billing, sibling routing, quote discipline). It is dense but not padded; the list of term categories is the only mildly verbose part.

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, billed, multi-parameter tool with an output schema, the description covers authorization (Pro), cost, limits, result-state meanings, citation expectations, and sibling disambiguation. An agent has everything needed to call and interpret it correctly.

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

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

With 67% schema coverage, the description adds real meaning: fields and topics narrow the answer, topics omitted returns every topic, and combined they intersect (echoed by schema). It also clarifies the 10-bond cap on identifiers, but doesn't illustrate identifier formats beyond the schema.

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

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

States a specific verb and resource ('Return the terms of up to 10 bonds as read from their offering documents') and enumerates the term categories covered. It also explicitly contrasts itself with sibling bondterminal_get_bonds, so an agent can distinguish the two without opening a schema.

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

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

Gives concrete usage guidance: 'Ask for topics or single fields to keep the answer short,' names the alternative (bondterminal_get_bonds) and says what to do when the two disagree ('show both'). Also states 'Pro only' as a precondition.

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 read-only and idempotent annotations, the description discloses authentication context, billing cost, and that it consumes no calculation or read units. It also clarifies that the tool returns no bond data and accepts no batch input, which is meaningful behavioral 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?

The description is short and front-loads the core purpose and return values. The sentence about YTM conventions, spreads, and bond prices is somewhat irrelevant for a tool that explicitly returns no bond data, though it does not significantly obscure the definition.

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 and full annotation coverage, the description need not explain every returned field. It still gives enough context: what the tool returns, that it is authenticated, that it is free, and that it consumes no units.

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

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

The tool has zero parameters, so there is no parameter semantics burden. The baseline score for a parameterless tool applies, and the description appropriately focuses on outputs and constraints rather than nonexistent inputs.

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, 'Return', and names the exact resources: authenticated plan, calculation/read usage, remaining quotas, and reset time. It also distinguishes itself from bond-data siblings by stating it returns no bond data and has no batch input.

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 intended use is clear from the listed outputs: checking plan, usage, quotas, and reset time. It adds useful when-not guidance by saying it returns no bond data and has no batch input, though it does not explicitly name a sibling tool to use instead for bond-related tasks.

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 declare a non-read-only, non-destructive, idempotent operation; the description adds real value on top by imposing a per-conversation dedupe rule, a privacy constraint ('Do not include personal data about the user'), and the fact that the message must be self-contained for a reader without the conversation. It does not say what happens to a submitted report or who consumes it, but the output schema covers the response side.

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?

Four short sentences, front-loaded with the core action, then exclusions, rate limit, privacy, and the sibling redirect. No sentence is redundant with the name or title.

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 write-side reporting tool with six params and an existing output schema, the description covers the trigger conditions, the dedupe budget, the privacy rule, and the alternative route. An agent has everything needed to decide and to call it correctly without guessing.

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 67% schema coverage the baseline is 3, and the description lifts it by mapping its trigger examples onto the category enum values (missing_capability, wrong_result, unclear_tool) and by scoping 'a missing bond' away from identifiers toward request_bond. The tool_error and 'other' categories remain unglossed, so it stops short of fully compensating.

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

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

The description gives a specific verb and target ('Report a gap in BondTerminal') and enumerates the triggering conditions: missing tool/field, wrong result, unclear description. It also names the sibling to use for a different case (bondterminal_request_bond), so the boundary is 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?

Explicit when-to-use is paired with explicit when-not-to-use ('searches you can fix by retrying or by using bondterminal_search_bonds'), a rate constraint ('at most once per distinct problem per conversation'), and a routing rule for missing bonds. This is the full when/when-not/alternative triad.

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=false, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds real context beyond that: this is a *request* (not a guarantee the bond will be added) and it requires explicit user consent. It stops short of saying what happens after submission (queued, reviewed, any follow-up), which would complete the behavioral picture.

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?

Three short sentences, each carrying a distinct fact (what, gating condition, input source), with the purpose front-loaded. No filler or repetition of the title.

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 explanation, and the core call path is clear for a 2-parameter tool. The remaining gaps are the undefined 'note' parameter and the missing contrast with bondterminal_report_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 0%, so the description must compensate. It does explain isin's provenance ('from a bondterminal_get_bonds miss'), but the second parameter 'note' is never mentioned — its purpose and the 300-character limit are only visible in the raw 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 ('Request that BondTerminal add a bond') and scopes it with the negative qualifier 'a bond it does not cover yet', which separates it from coverage-query siblings like bondterminal_get_bonds. An agent can identify the action 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?

Gives a hard precondition ('Call only after the user agreed') and a concrete trigger ('the ISIN from a bondterminal_get_bonds miss'), which is stronger than most definitions. It does not, however, distinguish this from the sibling bondterminal_report_gap, which an agent could plausibly confuse with requesting a missing bond.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely non-obvious traits: unit conventions (percent for YTM, basis points for spreads, prices per 100 face), hard caps of 730 days and 750 returned points, and a 1 read-unit billing cost for history. Missing: whether exceeding the caps errors or truncates, and any rate-limit/auth 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?

Three compact sentences: capability first, unit conventions second, caps and billing last — no filler. The units sentence is slightly boilerplate for a country-risk tool since bond prices per 100 face are not obviously part of this return value, which costs a point.

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?

Annotations cover safety and an output schema presumably covers the return shape, so omission of return details is fine. For a 4-param tool with 0% schema coverage and optional date filters, though, the description leaves the core parameter mechanics (range vs. explicit dates) unexplained, which is a gap an agent will notice when constructing a history call.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it never explains the `range` enum (1w/1m/3m/ytd/1y/2y), the date format for `start`/`end`, whether explicit dates override `range`, or the default of `include_history`. Only the 730-day/750-point history cap indirectly informs `start`/`end` usage, leaving most of the four parameters undocumented.

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 — 'Return the current Argentina country-risk spread and deltas' — with the optional history mode named up front. It does not distinguish itself from plausible siblings such as bondterminal_get_history or bondterminal_treasury_curve, so an agent must infer the boundary rather than read it.

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?

'With optional history' plus the billing sentence ('current snapshot is free; including history costs 1 read unit') gives a real decision cost that guides whether to set include_history. However, there is no explicit statement of when to prefer this over bondterminal_get_history or bondterminal_treasury_curve, and no note on how range/start/end interact for history requests.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, but the description adds substantial operational context: billing is 1 read unit per row with a minimum of 1, page size is capped at 500, and basic keys are limited to 50 rows per page. It also warns that oas is a deprecated alias with the same value as gSpread, not an option-adjusted spread. It stops short of describing auth requirements or error behavior, so it is strong but not complete.

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

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

The description is front-loaded with the core purpose and then packs in high-value operational details. It is dense and semicolon-heavy, but every sentence contributes something useful for calling or interpreting the tool.

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

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

The annotations and existing output schema reduce the burden, and the description covers billing, pagination caps, and key output-field conventions. However, for a complex screening tool with a large undocumented filter object, the description leaves important filter semantics and sibling-tool selection guidance unaddressed.

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

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

Schema description coverage is 0%, and the tool has a large nested filter surface. The description adds useful units for yield and spread interpretation (YTM in percent S.A., spreads in basis points, EUR spread exception over Bund) and restates the page-size cap, but it does not explain most filter parameters such as ratingMin/Max, hideStaleBonds, includeMatured, duration bounds, or outstanding balance filters.

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

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

The description gives a specific verb and resource: search and screen bonds by free text and REST-compatible filters, with optional facets. It is clear on its face, but it does not explicitly distinguish itself from sibling tools such as bondterminal_get_bonds or bondterminal_request_bond.

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

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

Usage is implied by 'search and screen bonds by free text and REST-compatible filters,' and the optional facets flag is noted. However, there is no explicit when-to-use versus alternatives guidance, no exclusion conditions, and no routing to get_bonds for direct identifier lookup.

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, non-destructive behavior, yet the description adds substantial context beyond them: Pro-tier gating, beta status, a concrete billing cost (10 read units per call), passage caps, and per-account daily quotas. It also discloses that passages are verbatim untrusted text and warns against following them as instructions, which is exactly the kind of safety-relevant trait annotations cannot express.

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?

Four tight sentences ordered by importance: capability, safety warning, language handling, then cost/limits. Nothing is repeated from the schema verbatim and no sentence is filler.

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

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

With an output schema present, the description doesn't need to enumerate return fields, and it instead covers everything an agent needs to decide and call correctly: tier, cost, throughput caps, untrusted-content handling, and translation behavior. No material gap remains for this complexity level.

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

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

Schema coverage is 75% with one enum documented in the schema, but the description still adds meaning: 'up to 25 chosen bonds' reinforces maxItems, 'up to 10 passages per call' explains the limit ceiling, and 'words or a clause' frames how query and clause interact. It stops short of explaining the clause-plus-empty-query fallback, which lives only 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 (search the offering documents of chosen bonds) plus the scope constraint (up to 25 bonds) and the return shape (cited passages with document and page). This is clearly distinguishable from bondterminal_search_bonds, which searches for bonds rather than inside their documents.

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 'Pro only, beta' gate and quota limits tell an agent who may call it and how much they can call it, but there is no explicit when-to-use or when-not-to-use guidance versus siblings like search_bonds or get_terms. Usage is implied by the resource described rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is handled. The description adds real value beyond that: unit conventions (percent, basis points, price per 100 face), a response cap of 11 tenors, and billing cost (free, no calculation or read units consumed).

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?

Three short sentences, each carrying distinct information (scope, units, cost), with the core purpose front-loaded. Nothing is redundant with the title or schema.

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

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

An output schema exists, so return structure need not be described, and the description fills the remaining gaps (units, cap, billing). Minor gap: 'the 11 listed tenors' is never enumerated, so the agent cannot know which tenors without inspecting the output 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The note that output is capped at the 11 standard tenors gives useful shape to an otherwise argument-free call.

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: 'Return the current US Treasury curve across 11 standard tenors'. No sibling tool returns curve data, so the resource alone distinguishes it from calculate, get_bonds, get_history, etc.

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 word 'current' implies a live snapshot rather than historical series, which weakly separates it from bondterminal_get_history, but no alternative is named and no when-to-use/when-not-to-use condition is given. Usage must be inferred from the resource name.

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