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

Annotations already mark the tool readOnly, idempotent, and not destructive. The description adds meaningful behavioral context: it compares only electable plans, lists ineligible plans with reasons, and unconditionally runs the consolidation path for Parent PLUS. The warning that 'loanType drives PLAN ELIGIBILITY, not just the rate' also reveals how the input affects behavior beyond a simple calculation.

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 sentences, each earning its place: scope and outputs, ineligible plan behavior, the important Parent PLUS special case, and a caution about a critical parameter. It is front-loaded with the core purpose and has 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?

With no output schema, the description fills the gap well by enumerating comparison outputs (monthly payment, lifetime cost, forgiveness timing, estimated tax) and the ineligible-plan reason list. It also covers the key special case and input caution. Minor gaps remain: it does not describe the shape or currency/period of returned values, but it is otherwise sufficiently complete for a complex 7-parameter 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%, so the baseline is 3. The description adds real value by emphasizing that loanType determines plan eligibility, not just the rate, and by tying the Parent PLUS consolidation behavior to loanType. This goes beyond the schema's enum-like listing.

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 ('Compare') with a concrete resource ('every federal repayment plan a loan can elect') and names the exact plan set (Standard, RAP, IBR, PAYE, ICR). It also names the output dimensions, which distinguishes it from siblings like estimate_rap_monthly_payment and compare_married_filing_jointly_vs_separately_student_loans.

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 clearly states context: use it to compare all eligible repayment plans and see ineligible plans with reasons. It also gives a specific routing rule for Parent PLUS ('runs the consolidation path unprompted, because that is the number that decides'). It does not explicitly say when not to use it or name alternatives, 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.