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

The annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds substantial behavioral detail beyond that: deduplication, _warnings, missing_ids, restricted_ids, 403 semantics, credit cost formula, and endpoint reference. This is far beyond the baseline.

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 dense but every sentence adds value, covering usage, edge cases, and cost. It is front-loaded with the core relationship to get_insider_stats. The length is justified by the tool's complex behavior, though it could be slightly better organized.

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's complexity and the absence of an output schema, the description covers key edge cases, error conditions, and credit costs. It references the output shape via list_insider_transactions, which is adequate, though a bit more detail on the normal successful response payload would make it fully self-contained.

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 100%, so the schema fully documents page, page_size, and transaction_ids. The description adds useful context that transaction_ids come from get_insider_stats, but it does not need to compensate for missing schema information.

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 states a specific verb and resource: fetch insider transactions by id. It clearly distinguishes itself as a 'detail companion to get_insider_stats' and references the same shape as list_insider_transactions, so an agent can differentiate it from siblings.

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 gives explicit context for when to use it: after get_insider_stats returns transaction_ids. It also explains edge-case behavior for missing and restricted ids. It does not explicitly state when not to use it versus alternatives, but the companion relationship is a strong usage signal.

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