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

Annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to restate safety. It adds value by disclosing the default output behavior ('summary' returns totals plus per-year breakdown), the need to paginate with offset/limit for 'monthly', and the non-advisory nature ('no advice'). This goes beyond the structured metadata and helps set expectations for the tool's 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?

The description is four sentences, each with distinct value: purpose, features, output behavior, and output type/disclaimer. It is front-loaded with the core purpose, avoids redundancy, and does not waste words. The only minor omission is not explicitly naming the 'yearly' enum value, but the description still conveys that summary includes yearly breakdown.

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 complexity (12 parameters, nested optional arrays), the description provides a good high-level map: core function, key optional inputs, output modes, and pagination. The schema covers parameter details and an output schema exists, so the description doesn't need to explain return structures. It could mention the 'yearly' detail option or clarify 'rate-fixed period' more, but these are minor gaps given the rich 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 100%, with each parameter clearly documented (e.g., rate 'in percent', mode semantics, offset/limit purpose). The description mostly restates what the schema already provides, such as detail options and pagination, without adding new parameter-level insights. The baseline of 3 is appropriate because 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 opens with a specific resource: 'Monthly loan amortization schedule and summary.' It clearly distinguishes the tool from more general financial calculators by focusing on amortization with monthly detail and summary output. The scope (loan amortization) and key features (extra principal payments, rate-fixed period) are immediately evident.

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 explaining output options ('detail controls output size') and capabilities ('Supports dated extra principal payments and a rate-fixed period'), but it does not explicitly state when to choose this over sibling tools like loan-payoff or biweekly-payoff. There are no explicit alternatives or exclusion conditions, leaving the agent to infer applicability from the tool's name and features.

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