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

Despite annotations already declaring this a safe read, the description adds substantial behavioral context beyond them: the entitlement model (first 5 rows then a count by type via locked.count/locked.by_type), field-level redaction (contact values and decision-maker names never returned, only types/counts), the guarantee that street addresses are never read, and the `entitlement`/`locked` self-disclosure. This is exactly the kind of access and data-exposure detail 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?

It is front-loaded with the resource and ranking options before the access caveats, and every clause carries information the schema lacks. The sentences are long and densely packed, which slightly hurts readability, but there is no filler.

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 and 7 loosely documented parameters, the description does the heavy lifting: it defines the record, the sort semantics, the filters, and the entitlement/redaction behavior. The main remaining gap is pagination mechanics (how `cursor` interacts with the 5-row lock), but overall it 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 low (29%), so the description must compensate, and it does: it enumerates the sort keys and, crucially, explains what they mean (departures, joins, net flow, departure rate, team lift-outs, breakaways in formation), which the bare enum does not. It also maps the firm CRD / state / class / minimum advisors filters. It omits any explanation of limit/cursor pagination, keeping it from a 5.

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 concrete verb+resource and defines the unit precisely as 'Offices (a firm and an IAPD branch city)', distinguishing branch-level granularity from the firm-level siblings like get_ria_firm. It lists the ranking dimensions, so an agent knows exactly what it returns. It stops short of naming a specific alternative to route away to, so it lands at 4 rather than 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?

Filter guidance is present ('Filter by firm CRD, state, class and minimum advisors'), which implies how to narrow results, but there is no explicit when-to-use vs when-not, and no routing to neighbors like search_ria_advisor_moves, search_ria_teams, or get_ria_trends. Usage is left to inference from the resource description.

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