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

Goes well past the readOnly/idempotent annotations: it discloses the entitlement behavior in detail (unpaid callers get 5 full rows plus a locked count/by_type, never the rest), states that contact values and decision-maker names are never returned, explains that withholding is always reported in `entitlement` and `locked`, and declares that disclosure_status is uniformly DISCLOSED_OBA so nothing is ever labeled undisclosed. This is exactly the kind of operational context an agent needs before calling.

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 core content is front-loaded in the first sentence, but the description is a single dense block of run-on clauses, and the entitlement/plan pitch plus the 'does not predict a move' aside dilute the operational signal. Much of it earns its place, yet it could be restructured into scannable statements without losing information.

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 13-parameter, no-output-schema search tool, the description covers the return shape (what each row contains), cohort scope, filter semantics, and entitlement limits, and the annotations already carry the safety profile. Remaining gaps are minor: pagination/sort behavior and the limit ceiling are only implicit, but nothing critical to calling it correctly is missing.

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 only 46%, but the description compensates by naming nearly every filter parameter in plain language and giving each a meaningful mapping (company name contains, category, category group, materiality, investment related, role, start date, current only, current firm CRD or branch state). Sort, limit, and cursor are left to the schema alone, which is acceptable given the cursor is documented there.

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 precisely what the tool returns: outside-business entries from the advisor's own Form U4 disclosure, with the row fields enumerated (company, basis, role, ownership, dates, materiality, verbatim evidence, name and current firm). It implicitly separates itself from the single-record sibling by describing list-level behavior ('a list returns its first 5 rows', 'a record names its subject'). An agent knows this is the cohort-wide list/search of OBA entries, not a per-advisor lookup.

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 enumerates the available filter axes (company, category, category group, materiality, investment related, role, start date, current only, firm CRD, branch state), which implies how to narrow a search, and scopes the data to the ~2,500-advisor reviewed cohort. However, it never says when to reach for this tool versus siblings like get_ria_outside_business or search_ria_advisor_moves, and the cryptic aside that outside business 'does not predict a move in general; the caveats name the two measured exceptions' gestures at a distinction without resolving it.

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