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

Annotations already declare readOnly/idempotent/openWorld, and the description adds real context beyond them: pagination at 100 per page, ticker-holding companies ordered first, listed_only defaulting True and what setting it False surfaces (dormant, delisted, asset-backed entities). The caveats that SIC is assigned at registration, is not GICS/NAICS, and is absent for individuals and most funds are exactly the kind of domain trap an agent needs flagged.

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?

Front-loaded with the action and an example code, then the fallback, then caveats, then args. The closing 'Args:' block largely restates the prose above (industry, page size, listed_only), so it is slightly longer than strictly necessary, but nothing is buried or wasteful enough to hinder scanning.

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?

An output schema exists, yet the description still tells the agent the shape of a row and the ordering, and it fully covers the dual-mode input, the drill-down workflow, and the classification caveats. Nothing needed to call this correctly or interpret results 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 0%, so the description must carry the full burden and does: industry accepts either a 3-4 digit code or an industry word, query filters name/ticker with a code, page is 1-indexed at 100 per page, and listed_only's default and effect are spelled out. Each of the four parameters is given meaning the bare schema does not.

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?

States a specific verb and resource ('List the companies in an industry') and pins it to the SEC's SIC classification, which separates it from search_companies and list_sic_codes. It also names the exact fields returned (CIK, name, ticker, state, fiscal year end), so an agent knows what it gets without opening the schema.

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?

Gives explicit routing: use get_company or search_companies for a company's own code, list_sic_codes for the whole classification, and this tool for the companies in a code. It even handles the unknown-code case by describing the word-lookup fallback on the same tool, then tells the agent to re-call with the returned code.

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