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

Goes well beyond the readOnly/idempotent/non-destructive annotations by disclosing the entitlement model: free tier returns only the first 5 rows plus locked.count/locked.by_type, records name only their subject and first 3 related names, and contact values/decision-maker names are withheld but reported as types and counts. It also flags that 13F covers only US-listed long equity, so private holdings are absent.

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?

One dense paragraph, front-loaded with purpose and return fields, followed by input guidance and access constraints. Every sentence earns its place, though the trailing plan/pricing pitch is slightly promotional rather than functional.

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 return-shape burden and does so thoroughly (field-by-field), plus covers access restrictions and the 13F coverage limitation. For a 6-parameter, no-required, no-output-schema tool this is complete enough to call correctly.

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 high (83%), so the baseline is 3, but the description adds real meaning: it supplies example SIC codes (3674, 6021/6022, 1311, 2834, 7372), explains that a sector word is matched against the SEC SIC description, and clarifies the CUSIP→ticker→CIK→EDGAR SIC chain behind sector assignment.

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 (search) plus resource (family office / 13F filers holding a sector) and enumerates exactly what is returned per office (value, positions, share of book, top five, class, state, filing). It also implicitly distinguishes itself from sibling list tools by scoping to sector holdings on the 13F graph.

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?

The description explains the family_capital_only toggle and how to express a sector (SIC codes or a sector word), which is usage context, but it never names an alternative tool or states when to prefer search_family_offices / search_family_office_investments over this one. Usage is implied rather than prescribed.

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