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

Annotations already establish read-only, idempotent, open-world, non-destructive behavior, so the description only needs to add context beyond safety. It does add meaningful behavioral context by disclosing that this endpoint aggregates multiple distinct data sets into one response, which implies a larger combined payload than a single-purpose endpoint. It does not mention latency or output shape, but with annotations covering the safety profile this is a reasonable contribution.

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 short and front-loaded: the first line states the core value proposition and the included categories. Minor marketing phrasing like 'mega-endpoint' and the redundant 'everything we know' label add a little color without adding much information, but overall it is efficiently written.

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?

This is a complex 10-parameter aggregator with no output schema and dozens of narrower sibling tools. The description does not clarify which identifier parameter to provide, whether at least one is required, what the response structure looks like, or how this relates to focused tools like company_enrich. An agent can infer broad intent but not safely invoke it for a specific use case without more guidance.

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 only 10%, with just include_filings documented. The description does not explain how to choose between lei, domain, and ticker, whether any identifier is required, or how the include_* flags map to the listed data categories. For a heavily optional-flag endpoint with low schema coverage, the description supplies almost no parameter-level meaning.

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 clearly identifies this as a single-call aggregate company endpoint and enumerates the bundled data categories: profile, hierarchy, corporate-family network, lifecycle timeline, and peer benchmark. This distinguishes it from narrower company tools, though it relies on a label ('everything we know') rather than a precise verb and resource 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?

It implies use when you want broad company intelligence in one call ('Single-call mega-endpoint', 'everything we know'), which is useful guidance. However, it never states when not to use it or names alternatives like company_enrich, company_network, company_timeline, or company_peer_comparison, leaving routing to inference despite many siblings.

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