insider_transactions

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

With no annotations, the description carries the full behavioral burden. It does disclose one genuinely useful trait — that past-dated data is withheld because records are dated by trade date rather than filing date — which is real context an agent could not get from the schema. However, permissions, completeness of recent data, and cardinality/ordering of results are all unstated.

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 short sentences with no filler, and the constraint is placed up front. But the terseness crosses into opacity: the pronoun "they" is unresolved and the second sentence reads as a fragment the agent must reverse-engineer.

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, so return values need not be explained, which relieves some burden. Still, a two-parameter data-retrieval tool with zero schema coverage and no annotations leaves the as_of behavior and the meaning of a withheld range unexplained — enough is missing that an agent could mis-call it.

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% across two parameters, so the description must compensate and largely does not: "ticker" is never mentioned, and "as_of" is only obliquely hinted at by "withheld for past dates." The phrase "they are dated by trade rather than by filing" is ambiguous — "they" has no clear referent — and does not tell the agent what format as_of takes or what happens when it is null.

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?

"Insider buys and sells" names the resource (insider trading activity) but offers no verb and no scope — it does not say whether it returns a list of transactions, a summary, or aggregated net activity. It is not distinguished from siblings like fundamentals or company_news, which a reader must infer are different report types.

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?

There is no statement of when to call this rather than fundamentals or company_news, and no guidance on when as_of matters. The second sentence explains a data caveat rather than a usage condition, so an agent gets no routing help.

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