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

Goes well beyond the readOnly/idempotent/no-side-effect annotations by disclosing that free-tier calls return only the first 5 rows plus locked.count/locked.by_type, that a record shows its subject and the first 3 related names, that contact values and decision-maker names are never returned, and that precision by basis is unsampled while a name is never a basis. This is exactly the kind of entitlement and edge-case context an agent cannot get from structured fields.

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 purpose and the routing question are front-loaded before the access caveats, and most sentences carry real information. It is dense and run-on in places, and the trailing promotional plan link is less essential, keeping it short of a 5.

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 complex tool with no output schema, the description covers the return shape (links with their printed basis), the identifier substrates, and the full entitlement/locking story. The only real gap is the limit parameter's semantics, which is minor against the otherwise thorough behavioral disclosure.

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 50%; the dfx_id schema already documents the dfx:ria:<uuid> and CRD forms the description repeats, adding little. The limit parameter is undocumented in both schema and description, though 'the 200 largest funds are checked' loosely hints at its ceiling. Baseline 3 for a half-covered schema.

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?

States a specific verb and resource: it returns every link from an RIA firm (or one private fund) to the PE, VC, family office and sponsor graphs written on a shared identifier, and even names the question it answers. The scope is unusually precise, but it never explicitly names a sibling tool it should be chosen over.

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?

'Answers which PE or VC graph entities hold vehicles this wealth manager advises' implies a use case, and the accepted identifier forms (dfx:ria: firm or fund id, or a firm CRD) imply when the tool applies. There is no explicit when-not guidance or pointer to an alternative such as get_capital_paths or get_ria_firm.

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