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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered by structured data. The description adds one useful behavioral fact — that results are ranked and carry fit/fail reasons — but says nothing about scoring methodology, determinism of ordering, or how many programs are returned.

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?

A single dense sentence with the action and the output shape front-loaded and zero filler. Nothing could be removed without losing content.

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?

There is no output schema, so the description is the only place the return shape can be described, and it only gestures at it ("ranked programs with reasons"). With six parameters and a close-named sibling (compare_programs), the definition should do more to say what comes back and how it differs from a plain comparison.

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 all six parameters (units, occupancy, loan, hold, reno, recourse) are documented in the schema itself. The description adds no meaning beyond the schema, so the baseline 3 applies.

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 pairs a specific verb ("Rank") with a specific resource ("loan programs") and scope ("for a deal"), plus an output hint ("reasons each fits or fails"). It is clear what the tool does, but it never distinguishes itself from the sibling compare_programs, which a reader could easily mistake for the same operation.

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 only implied by "for a deal" — the agent can infer this is the deal-time matching step, but there is no statement of when to prefer it over compare_programs or check_eligibility. No prerequisites, no exclusions, no explicit alternative routing.

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