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

With no annotations provided, the description carries the full burden and discloses a critical behavioral trait: during backfill, newly-opened quarters are incomplete and flagged as still loading, preventing naive misinterpretation of QoQ changes. It does not describe the exact output format or return response, but the key behavioral nuance is well covered.

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 front-loaded with the core purpose in the first sentence and adds the crucial caveat and parameter guidance in the second. Every sentence provides valuable information with no fluff or repetition.

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?

Given the tool is a simple coverage/status tool with one optional parameter and no output schema, the description fully equips an agent: it explains what is returned per quarter, how to detect incomplete data, when to call it, and how to scope it by ticker. The critical use-case warning about backfill makes it complete for correct 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?

The schema has zero description coverage, so the description must compensate. It explicitly explains the only parameter, ticker, as a way to get per-company coverage, implying it is optional and affects scope. This adds meaningful meaning beyond the bare schema field, though it does not specify ticker format or the default aggregate behavior in detail.

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 reports 'how much institutional-ownership history has actually landed' per quarter, with specific metrics (rows, securities, distinct holders) and a loading flag. This distinctly positions it as a coverage/status tool versus actual holdings tools like tengu_v3_intel_top_shareholders or tengu_v3_intel_top_shareholders_current.

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 explicitly instructs to call it 'BEFORE treating a quarter-on-quarter change as a real position change' and explains the backfill incompleteness risk, which is strong when-to-use guidance. It also tells the agent to pass a ticker for per-company coverage, but it does not explicitly contrast with alternative tools or state when not to use it.

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