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

Annotations already declare readOnlyHint/idempotentHint true, and the description goes far beyond them: grouped-mode txn_count is the company's full hit count not the page's, credit cost is dynamic (65-920) and charged even on empty results and 504 timeouts, results are gated by Pro plan and limited to the plan's history window/company coverage, and rows carry a computed block with value/status/inputs. This is unusually rich behavioral disclosure that materially changes how an agent should plan and budget the call.

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 long but every sentence carries operational value: purpose and filter levels are front-loaded in sentence one, followed by output shape, a subtle counting gotcha, pagination limits, cost behavior, and plan gating. The tail ('POST /api/v1/screener/ownership; FINANCIAL_API_DOCUMENTATION.md') is slightly miscellaneous for an MCP context where the transport is already known, but it does not bloat the core message. Well-ordered and dense, if not terse.

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?

For a 12-parameter composite-filter tool with no output schema, the description is remarkably complete: it covers the output row structure (issuer_cik, accession_number, filing_date, source_url_prefix, insiders, computed block), grouped-mode semantics, pagination cap, cost/error behavior, and plan restrictions. The only gap — a full response schema — is partially compensated by the row-composition sentence, and the input side is already fully specified by the 100%-covered schema.

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?

Despite 100% schema coverage (baseline 3), the description adds substantial cross-parameter meaning the schema alone cannot convey: the trade_filters vs aggregate_filters distinction, the shared operator syntax (> , >=, <, <=, between), the guidance to prefer split_adjusted_shares/prices over filed values when the window spans a corporate action, and the page x page_size <= 500 constraint. This lifts the semantics well above the schema's individual field descriptions.

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+resource+scope — 'Screen insider trades across the whole library' — and immediately distinguishes this from the sibling list/get tools (list_insider_transactions, get_insider_transactions_by_id) by emphasizing whole-library screening with two layered filter levels. The 'Screener:' title prefix plus the filter-level breakdown make the tool's identity unambiguous even before an agent looks at the schema.

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 clear context on when to use the tool: whenever an agent needs to screen the whole library with trade-level and company-level conditions. It thoroughly explains the operators, filter payload shapes, grouped-vs-flat modes, and the split-adjusted field guidance for corporate-action windows. However, it never explicitly names sibling alternatives or states when NOT to use it (e.g., when fetching a known transaction by ID), so it stops short of a full when/when-not routing.

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