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

The description goes far beyond the readOnlyHint/openWorldHint/idempotentHint annotations by disclosing fan-out behavior, soft-fail handling (USPTO sunset May 2025), the meaning of empty returns ('a real "no data", not a bug'), the sources_used/sources_failed mechanism, and the resolved:false path for private companies. It also reveals that an fda_products empty result is expected for non-biologics companies, preventing false-positive interpretation. No contradictions with 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 it is packed with necessary behavioral and return-value detail that an agent needs in the absence of an output schema. It front-loads user phrases and the core directive before diving into output fields. The structure is somewhat run-on — a single dense paragraph with semicolon-separated sections — but every sentence earns its place, so the length is justified.

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?

Given there is no output schema and the tool fans out across many sources, the description documents each return section (cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI) and their caveats, plus the success/failure reporting mechanism. It also covers all three input forms and the private-company failure mode. An agent has everything needed to call it correctly and interpret responses 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 100%, so the baseline is 3, but the description adds real value: it gives concrete examples for each accepted value shape, explains that names resolve via SEC EDGAR company-name match, and clarifies that 'type' accepts 'company' or 'ticker' interchangeably. This enriches the schema rather than merely repeating it, though the schema already carries the core definitions.

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-phrase examples, then states the exact function: 'full cross-source profile of a US public company in ONE parallel call.' It explicitly distinguishes itself from chaining single-pack lookups and from related siblings like compare_entities and resolve_entity by naming the holistic use case. The verb 'profile' plus the resource scope (US public company across SEC/XBRL/patents/etc.) leaves no ambiguity about what the tool 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?

Usage is explicitly conditional: use when the user asks for a holistic view or says 'tell me about X' / 'research Acme', and 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' It also states acceptable inputs (ticker, CIK, company name), the private-company edge behavior, and what 'type' values mean. This is clear when-to-use guidance with no reliance on inference.

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