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

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond them by disclosing the endpoint, cost (0.005 credits per call), and an anonymous rate limit (25 calls/day per address with no credentials). That is exactly the kind of auth/cost/limit context an agent needs. It stops short of describing pagination or ordering behavior.

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?

Two tight sentences with the core resource and metadata front-loaded, followed by filtering options and then operational details in a compact parenthetical. Nothing is padded, though the metadata list and filter list slightly overlap.

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?

With no output schema, the description partially compensates by naming the fields a thesis carries (sentiment, conviction, price target, DVI run), and it covers auth/cost limits. It is a zero-required-parameter read tool, so the remaining gap — return shape/pagination — is modest but present.

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 load, but it only restates three parameter names (ticker, conviction, sentiment) without adding meaning — e.g., no explanation of the 1–5 conviction scale or the role/default of `limit`. It also omits the fourth parameter entirely, leaving the schema's bare types as the only documentation.

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 resource — public investment theses with structured metadata (sentiment, conviction, price target, DVI run) — which is a coherent, retrievable entity and clearly not the same as the aggregate `sentiment` or `research` siblings. It does not, however, explicitly name or contrast with any sibling, so an agent must infer the boundary.

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 tells the agent which fields can be used to filter (ticker, conviction, sentiment), which implies the intended usage, but gives no when-to-use vs. alternatives guidance and no exclusions. There is no signal about when to prefer this over `sentiment`, `research`, or `verdict`.

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