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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses important runtime behaviors: the USPTO patents source soft-fails, fda_products may legitimately be empty for non-biologic companies, empty sections mean real absence of data rather than a bug, and private companies return resolved:false with a notes line. These are exactly the kind of behavioral details an agent needs.

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 and front-loaded with trigger phrases and the core preference rule. Every clause carries information about sources, return fields, or failure behavior. It is long, but the tool is complex and the length is largely necessary; could be slightly improved with structured bullets, hence not a 5.

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?

There is no output schema, so the description shoulders the burden of explaining return values. It lists all major result sections, provides example URI patterns, explains sources_used/sources_failed, and covers edge cases such as soft-fails, empty expected results, and private companies. Nothing critical is missing for an agent to call this 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?

The schema already covers both parameters completely, but the description adds meaningful semantics: names resolve via SEC EDGAR, resolved_from/resolved_to can appear when a name is passed, and both type values accept the same value shapes. This goes beyond the schema’s field descriptions without being redundant.

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 intents (“Tell me about X”, “research Acme”) and defines a specific operation: producing a full cross-source profile of a US public company in a single call. It distinguishes itself from single-pack SEC/XBRL/news lookups and clearly enumerates the return sections, so an agent can tell this apart from sibling tools.

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 explicitly says to ALWAYS PREFER this tool over chaining single-pack lookups when the user asks for a holistic view, which is a strong when-to-use directive. It also covers input alternatives (ticker, CIK, company name), the interchangeable type values, private-company behavior, and how to interpret empty sections, leaving little ambiguity about when and how to invoke it.

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