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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses substantial behavior: entitlement-gated results (first 5 rows plus locked.count/locked.by_type without a paid plan), fields never returned (contact values, decision-maker names), the 2011 ADV tape start and coverage caveats, quarantine handling, and the blind-label restriction on holdings. This is exactly the kind of context annotations cannot carry.

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?

Returns are front-loaded, which is good, but the body is a dense run-on covering return fields, coverage history, ownership caveats, entitlement mechanics and a marketing CTA. The plan pitch URL is promotional rather than operational, and several sentences could be split or trimmed without losing meaning.

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 carries the burden of describing returns and does so field-by-field, and it explains access limits and data-coverage windows. What is missing is pagination behavior for the cursor parameter and how sort/limit interact with the entitlement row cap, leaving a small gap for correct multi-page use.

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 60%, so the description must compensate, and it does add meaning for the two primary selectors: manager_dfx_id accepts a dfx:ref UUID or CRD, and lender matches by name, with the two input modes explained. It is thinner on cursor/limit/sort/min_loans/since, which fall back on the schema, so it improves on the schema without covering everything.

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 list ('Manager by lender pairs from the loans at the manager's validated holdings') and then names the exact output fields. It distinguishes the tool from siblings explicitly ('Use this for who financed <real estate manager>, not the corporate private credit tools') and notes the securitization/trustee exclusion. An agent can tell what this returns and what it is not without opening the 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 gives clear invocation modes ('Give a manager ... for its lenders, or a lender name for the managers it finances') and names exclusions (trusts/trustees, corporate private credit tools). However, it does not point to the closest named alternatives such as find_lenders_for_financing or find_real_estate_lenders, so routing among near-duplicate siblings still requires inference.

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