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

Annotations declare read-only, open-world, idempotent, and non-destructive behavior, and the description richly supplements these: it reveals parallel fanout, soft-failure for patents, expected-empty fda_products, resolved:false handling for private companies, and the semantics of sources_used/sources_failed. This goes far beyond the annotations and prevents misinterpretation of empty sections as bugs.

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 long but densely packed with behaviorally relevant details, organized by output section and with key guidance front-loaded ('ALWAYS PREFER'). Each sentence adds information; nothing is filler. It is not maximally concise due to the large number of edge-case disclosures, but those are necessary for correct invocation of such a broad tool.

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 carries the full burden of explaining return values, and it does so thoroughly: it enumerates every output field, notes maximum counts, explains URI formats, documents fallback chains, and clarifies expected empty and soft-fail conditions. An agent can invoke the tool and correctly interpret its results without external documentation.

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 100%, so the baseline is 3, but the description adds meaningful detail: it clarifies that type 'company' and 'ticker' are interchangeable, that value accepts ticker, zero-padded CIK, or name, and that names resolve via SEC EDGAR. It also communicates the resolved:false outcome for private companies, which is beyond the schema. The only reason it is not 5 is that much of this information also appears in 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?

The description opens with concrete user phrasings and immediately defines the core purpose: 'full cross-source profile of a US public company in ONE parallel call.' It clearly states the resource (a company) and the action (build a profile), and distinguishes itself by explicitly warning against chaining single-pack lookups for holistic questions. This is a precise, differentiated purpose statement.

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 gives an explicit selection rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also explains what inputs are acceptable, how names resolve, and what happens for private companies. This tells an agent exactly when and how to invoke the tool versus alternatives.

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