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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety is covered. The description adds context the annotations cannot: 'Source: FINRA BrokerCheck public API. No API key required,' which tells the agent no auth setup is needed. It stops short of stating rate limits or the 12-row page cap, which sits only in the schema.

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?

Front-loaded with the one-sentence purpose, then organized into scannable use-case bullets and a clearly labeled workflow paragraph. Every block contributes routing information; nothing is repeated 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 annotations, an output schema, and a well-documented nested parameter schema, the description covers what an agent needs to select and route correctly. Minor gaps: it does not say what happens when 'name' is omitted, nor mention the cached-result workflow (source_resource_id) that matters for follow-up queries.

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?

The description calls out 'name' and the optional 2-letter 'state' narrowing, but both are already documented in the nested schema, and it says nothing about rows/start pagination, include_previous, source_resource_id, or the internal wholesaler_ids filter. With the nested schema carrying rich per-field descriptions, the description adds only marginal parameter value; ignoring source_resource_id's cache-reuse behavior in the prose is the biggest miss.

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 and resource ('Search FINRA BrokerCheck for registered individual brokers') and scopes it to individuals, distinguishing it from SearchBrokerCheckFirm which handles firms. The description of returned fields (CRD, current firm, registration status, disclosures) confirms the scope without opening the schema.

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?

Contains an explicit 'Use this tool when' list covering CRD lookup, status verification, and record enrichment, plus a named alternative (GetBrokerCheckDetail) for full profiles. It even supplies a multi-step geographic workflow routing through SearchBrokersByPlace and SearchBrokerCheckFirm when the name is unknown.

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