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

Beyond the readOnly/idempotent annotations, the description discloses the disambiguation rule (multiple matches returns matches and no profile, except an exact display-name match which wins), the digit-to-NMLS interpretation, and the refusal vocabulary (no_match, ambiguous, no_profile) with the promise of never returning an empty object. It also clarifies that the returned NMLS ID is self-supplied by the lender and is identification-only, which prevents misuse of that field as a verified fact.

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 return content is front-loaded and nearly every sentence carries new constraints (ambiguity policy, NMLS interpretation, exclusions, refusal codes). There is minor redundancy in the closing rate disclaimer ('No rate appears here and FRU never publishes which lender has the best rate'), and the long multi-clause sentences slow scanning, but no sentence is 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?

For a single-parameter, read-only lookup with no output schema, the description covers everything needed: what fields come back, how input is interpreted, how ambiguity is resolved, and the exact failure vocabulary. An agent can call it and handle every outcome without consulting other sources.

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, and the description genuinely adds meaning: it states that digit-only input is parsed as a company NMLS, that name matching is substring-capable against multiple published pages, and that an exact display-name match takes precedence. It omits only minor constraints such as the 191-character maximum and 1-character minimum.

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 the exact resource (a lender's published FreeRateUpdate page profile) and enumerates the fields returned: page URL, Overview/Mortgage options/How it works sections, loan types, and biography reviewer plus date. It also draws explicit boundaries against sibling data domains ('No rate appears here', 'NMLS-derived facts are not returned: licensed states, locations, and company details'), which separates it from the rates, figures, and score tools without needing to name them.

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 implied through the matching policy — a name can be ambiguous, an exact display-name match wins, and digits are treated as a company NMLS — so an agent can infer how to call it and what to do with an ambiguous result. However, no alternative tool is named and no condition says when to prefer this over get_lender_figures, get_lender_score, or get_lender_sec_figures, leaving the selection decision to inference.

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