finance.bond_ytm

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

Annotations already declare readOnly/idempotent/closed-world, so the description is free to add real behavioral context, and it does: the solver is Newton's method, failure to converge still returns a value flagged converged=false, and mid-period accrued interest is out of scope. These are exactly the failure-mode and scope facts an agent needs before trusting the output.

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

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

Purpose is front-loaded and every sentence carries information: parameters, the ytm annualization convention, then the convergence caveat and the scope limit. The parameter explanations are packed into one long run-on clause, which slightly hurts scanability, but there is no filler.

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

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

An output schema exists, so return values need not be explained, yet the description usefully flags the converged field as something to check. For a seven-parameter numerical solver the coverage is nearly complete; only tol and max_iter tuning behavior is left entirely to 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?

Schema description coverage is 0% — every parameter is a bare title — so the description must carry the load, and it documents five of seven: price/face as positive Decimal strings, coupon_rate as a decimal annual rate with an example (0.05), years as integer, freq as payments per year with default 2. The solver controls tol and max_iter remain undocumented in both schema and description, which is the only 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 opening states a specific verb and resource — computes a bond's yield to maturity — and even names the numerical method (Newton's method). It is unambiguous what the tool produces. It does not explicitly contrast itself with the nearest sibling, finance.bond_duration, 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?

The description gives a clear operational condition: check converged=false because a non-converging run still returns the last estimate. It also names an explicit exclusion — accrued interest between coupon dates is not supported — which tells the agent when not to use it. It stops short of naming alternatives for the unsupported case.

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