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

Annotations declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false. The description adds substantial behavioral context: it states these are read-only reads from external sources with no mutation, that parallel fan-out is performed, that empty sections mean 'real no data' not errors, that private companies return resolved:false with an explicit notes line, and that sources_used/sources_failed indicate which sources returned data. This goes far beyond the annotation signals and tells the agent exactly what to expect in the response — including the edge case of no data.

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 description is dense, with most of the content front-loaded around the purpose and the key routing directive. It is longer than ideal but every sentence earns its place by covering scope, sources, return flags, param formats, and an edge case. The list of sources is long and somewhat stream-of-consciousness, but it is informative. It loses a point only because the mid-section listing sources is a run-on that could be condensed; it is not the tightest possible formulation.

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 read-only investigative tool with no output schema, the description provides all the context an agent needs: what it returns (list of sections, sources_used, sources_failed, resolved flags), how to call it (three valid value shapes), what to expect on failure (resolved:false with notes), and how it differs from chained single lookup calls. With annotations covering safety and idempotency, nothing critical is missing for an agent to select and invoke this tool 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 description coverage is 100% and the description itself explicitly explains both parameter shapes: type accepts 'company' or 'ticker' interchangeably (both take the same value shapes), and value can be a ticker, zero-padded CIK, or a company name. The description also adds nuance: names resolve via SEC EDGAR company-name match, and a private company returns resolved:false. This fully covers parameter semantics beyond the schema's minimal enum and string types.

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 uses a specific verb ('full cross-source profile') plus a resource ('US public company') and explicitly distinguishes itself from chaining single-pack lookups. It even lists the exact data sources and adjacent sibling tools it is not (search_articles, get_article, resolve_entity). This clearly separates it from siblings and leaves no ambiguity about what it does.

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 says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' — an explicit when-to-use directive. It does not explicitly list the sibling tools it competes with, but the context signal from the sibling list and the phrase 'ALWAYS PREFER' communicates the selection rule clearly. For a tool whose whole value proposition is comprehensive fan-out, this is sufficient guidance.

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