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

Annotations already cover readOnlyHint, openWorldHint, and idempotentHint, so the description's burden is reduced. The description adds the linkage that accession numbers in results feed secedgar_get_filing, which is useful context beyond annotations. However, it does not disclose any other behavioral traits (e.g., potential pagination, response size, or that searches may return multiple entities), leaving those to be inferred from the schema and output schema.

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 two sentences with no filler. The first sentence front-loads the core purpose ('Find companies and retrieve entity info with optional recent filings'), and the second sentence adds the workflow context and linkage. Every clause earns its place, and the structure is clear and efficient.

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?

The description is complete for a tool that has a rich output schema and thorough parameter schemas. It explains the workflow linkage to secedgar_get_filing, which is the most important cross-tool context. It does not need to explain return values since the output schema exists. The only minor gap is the lack of explicit guidance on when to set include_filings to false, but that is covered in the parameter schema. Overall, nothing critical for a correct invocation is missing.

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 description coverage is 100%, so every parameter is thoroughly documented in the input schema. The description does not add extra meaning beyond what the schema provides—it mentions that the tool 'resolves tickers, names, or CIKs' which maps to the query parameter, but that is already in the query parameter's description. With full schema coverage, a score of 3 is the appropriate baseline; the description provides marginal added value but does not compensate for any gaps.

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 uses specific verbs ('find', 'retrieve') and a specific resource ('companies', 'entity info'). It clearly states what the tool does: resolves tickers, names, or CIKs to entity details. It also differentiates from siblings by naming secedgar_get_filing as the downstream tool that consumes the accession numbers, which distinguishes it from secedgar_search_filings and secedgar_get_filing.

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 frames this as the 'entry point for most EDGAR workflows' and explains how its results feed into secedgar_get_filing, providing clear direction on when to use it. However, it does not explicitly state when NOT to use it (e.g., for direct filing lookup without entity resolution) or mention alternatives like secedgar_search_filings. It implies the flow rather than spelling out exclusions, which is strong but not fully explicit.

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