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

The description goes well beyond the read-only annotations by disclosing access tiers, exactly what is withheld without a paid plan (locked counts, contact values, decision-maker names), and the entitlement/locked response fields. It also states important data caveats: targets are not actuals, disclosed holdings are not approvals, commitment dollars repeat, re-ups are the plan's own words, and estimates are labelled.

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 description is dense and front-loads what the graph contains, but it runs long and packs access restrictions, caveats, and a marketing URL into one paragraph. Much of the content is useful, yet the structure could be tighter and more scannable.

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?

Given 14 parameters, no output schema, and only partial schema coverage, the description provides strong context on data semantics, entity_type behavior, and access limitations. It still leaves several filter parameters unexplained, but the behavioral and entitlement coverage is unusually complete.

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 low at 29%, so the description must compensate for many of the 14 parameters. It adds meaning for entity_type and query (alias-aware, CalPERS resolves), but most filters such as sort, state, min_assets_usd, with_policy, allocator_class, consultant_class, with_commitments, include_components, and min_private_markets_target_pct are not explained beyond the 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?

The description identifies the resource as the capital-owner graph and enumerates the allocator types it covers, along with how entity_type changes the target set. It distinguishes itself from sibling search tools by scope, though it does not explicitly use the verb 'search' in the description text itself.

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 explains how to use entity_type variants and what a bare query does, which implies when each mode is useful. However, it never names alternatives or states when not to use this tool versus siblings like get_allocator or search_entities.

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