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

Annotations already declare a safe read-only, idempotent profile, and the description layers substantial extra behavior on top: entitlement gating (first 5 rows plus locked.count/by_type without a paid plan), permanent withholding of contact values and decision-maker names, and the fact that every answer reports what it withheld in `entitlement` and `locked`. This is exactly the kind of context annotations cannot supply.

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?

Content is front-loaded with the core definition, but the opening sentence is an extremely long run-on with nested parentheticals, and the access paragraph is dense. Most sentences carry real information, but the structure hurts readability and the density borders on unparseable.

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 12-param tool with no output schema and low schema coverage, the description carries the return-shape burden well, listing the fields a team carries (member count, dates, spread, headcount, share, succession, kind) and fully covering access limitations. It is nearly complete, with only pagination/sort behavior left implicit.

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?

With only 42% schema description coverage across 12 params, the description compensates well: it explains the from/to firm filters, kind, move type, state, min members/date, and that include_members 'lists the people'. It leaves sort, limit and cursor unexplained, so it is strong but not complete.

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 defines the resource precisely ('clusters of advisors who left the same firm for the same firm from the same branch state within a 14-day chain') and enumerates the kind taxonomy, so an agent knows exactly what a 'team' is and that this is a rule over dates rather than a claim of intent. It never names a sibling (e.g. search_ria_advisor_moves or search_ria_move_indicators) to differentiate the unit of analysis explicitly, keeping it short of a 5.

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 gives filtering guidance ('Filter by from or to firm, kind, move type, state, minimum members or date') and one behavioral routing rule ('left out unless asked for by kind'), which implies when to use it. But there is no explicit statement of when to prefer this over the many advisor-move/indicator siblings, so usage is only implied.

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