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

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=false; the description goes well beyond that by disclosing that a conditional write occurs only when confirmed is true, that missing numbers write nothing, that derived terms carry termSheetStaged false unless a sheet already exists, and that a walk_pending status is returned while a walk is queued. It also flags the human-in-the-loop constraint ('A person still decides') and the enum of suggestedOutcome values, capping at refer rather than approve.

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?

It is front-loaded with the outcome first and the safety boundaries second, and no sentence is filler. It is slightly over-compressed, though: telegraphic fragments like 'Never records a credit decision, never sends, never wires' and jargon such as 'Compact-10 APPROVED' assume domain vocabulary an agent may not share, costing a little parseability.

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 does the work of explaining returns: walk_pending status, termSheetStaged flag, and the suggestedOutcome vocabulary are all spelled out, which is exactly what an agent needs. Gaps remain around what a 'walk' or 'pack score' actually returns and what happens on partial failures, but for a six-parameter composite tool this is close to sufficient.

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 the schema already carries the per-field definitions including the confirmed-gates-persistence contract and the 'same as stage_term_sheet' pointers. The description restates that contract at a portfolio level ('confirmed true persists principalAmount, rateBps, and termMonths... missing numbers write nothing') but adds no format, range, or default information the schema lacks, and never mentions the 'event' 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?

The opening sentence names four concrete outputs (walk, pack score, draft memo, derived indicative terms) and immediately bounds the scope with 'Never records a credit decision, never sends, never wires.' That verb-plus-resource-plus-exclusion framing makes it clearly distinguishable from record_credit_decision, stage_term_sheet, and score_case_against_pack 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?

It states clearly when this tool applies versus the decision-recording sibling ('Never records a credit decision') and gives a workflow condition for the confirmed path ('confirmed true persists...'). What it lacks is explicit forward routing — it never says 'use stage_term_sheet to stage a sheet' or 'use record_credit_decision once the approver signs off', leaving the agent to infer the handoff from sibling names.

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