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

Beyond the readOnly/idempotent annotations, it discloses substantial behavior: default row exclusions (99,737-row bulk acquisitions, departures with no destination), the entitlement model (unpaid returns first 5 rows plus locked.count/locked.by_type counts, record pages name subject and only first 3 related names per section), and what is permanently withheld (contact values, decision-maker names). 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?

Dense but front-loaded: the core what/fields come first, then filters, then exclusions, then access rules. The trailing promotional line ('Full access: DFX Intelligence, 7 days free at...') is the one sentence that does not help an agent invoke the tool, but everything before it earns its place.

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 fully covers the return shape (locked.count, locked.by_type, entitlement, per-record related-name truncation) and the access tiers that determine what an agent can actually expect back. For a 10-parameter, entitlement-gated tool this is complete enough to call correctly without guessing.

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 meaningfully compensates: it explains from_dfx_id/to_dfx_id as the from/to firm filters, advisor_dfx_id, move_type (with concrete examples), and the date window. It does not clarify connected semantics such as limit being capped at 25 or how cursor interacts with since/until, leaving those to 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?

Opens with a precise verb+resource: advisors who left one firm and registered at another, and enumerates the exact fields returned (person, from/to firms with class, end/begin dates, gap, move type). It is clearly distinguishable from siblings like search_ria_move_indicators and search_ria_changes, and even states what it is not ('not a prediction of who will move').

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 names the filterable dimensions (from firm, to firm, advisor, move type, date window) so an agent knows what queries this tool answers, and clarifies the default exclusion of bulk re-registrations and destination-less departures with the include_bulk/include_departures overrides. It does not explicitly name a sibling alternative for 'who might move next' beyond the negative 'not a prediction' phrasing, so routing guidance is clear but not fully enumerated.

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