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

Annotations already convey read-only/idempotent hints, but the description adds valuable behavioral context: return format (one row per filing, filer names, max percent), exclusions (no item narrative text), the meaning of event_revision null, and data delay. This goes well beyond the structured annotations and sets accurate expectations.

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 concise, front-loaded with the core purpose, and every sentence provides useful detail without repetition. It is well-structured for consumption by an agent.

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 tool has a simple parameter set and an output schema, so the description does not need to explain return values. It fully covers critical context: data delay, recency, null handling, and exclusions, making the tool's behavior clear for selection and invocation.

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% with descriptive parameter definitions for both ticker and limit. The description reinforces that ticker is required and mentions 'recent filings only' as context, but it does not add substantive meaning beyond the schema. A baseline of 3 is appropriate.

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 states the tool's function: 'Get Schedule 13D/13G beneficial-ownership filings (activist and 5%+ large-holder stakes) for one company.' It specifies the resource (company filings), the verb (get), and the scope (one company, ticker required). It also differentiates from sibling tools by focusing on activist/large-holder filings rather than timelines or sale notices.

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 provides clear context for when to use the tool: it requires a ticker, targets recent filings only, and notes a 24-hour data delay. It does not explicitly exclude alternatives or mention when not to use it, but the context is unambiguous.

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