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

Annotations already declare readOnly/idempotent, so the bar is lower, but the description adds non-obvious behaviors: it fans out across five sources, lists exact return fields, discloses a known failure mode (USPTO PatentsView API sunset May 2025 with soft-fail) and describes a fallback chain (GDELT→GNews). These are valuable operational insights not present in annotations.

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 information-dense and well-structured: it front-loads purpose with examples, then covers sources, returns, constraints, and alternatives in a logical order. Minor redundancy exists (e.g., repeating the 'company' theme), but each sentence earns its place, making it slightly above average but not perfectly concise.

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 complex tool with no output schema, the description is remarkably complete: it covers input semantics, output fields, source fallbacks, a known failure mode, and when to prefer this tool over alternatives. This is sufficient for an agent to select and invoke the tool correctly without further clarification.

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 input schema already provides 100% parameter descriptions, including the enum for type and a detailed explanation of value (ticker or zero-padded CIK, names not supported). The description reiterates this with examples and adds the resolve_entity pointer, but does not meaningfully extend beyond the schema's own parameter explanations.

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 example queries ('Tell me about X', 'research Acme') and clearly states the tool produces a 'full cross-source profile of a US public company in ONE parallel call'. This distinguishes it from sibling tools like resolve_entity (name resolution) or compare_entities (comparison), and precisely specifies the action and resource.

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 explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. It also states a clear exclusion (names not supported) and directs users to resolve_entity first, naming a concrete alternative.

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