FilingSpy

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

Beyond the readOnly/idempotent annotations, it discloses that missing investors and capped results are labelled, and it explains the two-stage continuation model (nextOffset for flat pagination, resultPath/resultOffset for nested overflow recovery). It stops short of stating any rate limits or what a partial 'capped' result looks like in practice, but the mutation-safety surface is already covered by annotations.

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?

Front-loaded with purpose and outputs, then routing, then pagination — the ordering matches how an agent reads it. It is dense but every sentence carries information; the final pagination sentence is partly redundant with the offset/resultPath schema descriptions.

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?

There is no output schema, so the description must describe returns, and it does: totals, a split-adjusted holdings matrix, pairwise overlaps, unique top holdings, plus labelling of missing/capped data. Combined with the routing and continuation instructions, an agent has everything needed to call it correctly in one shot.

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 coverage is 100%, so most parameter meaning is already documented in the schema, including the slug formats and the period regex. The description only adds the notion of a 'common' vs explicitly requested period and restates the nextOffset-as-offset loop the schema already describes, so it does little beyond baseline.

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?

Opens with a specific verb and resource ('Compare 2–6 investors') plus the scope ('one common or requested period'), then enumerates the concrete outputs (portfolio totals, shared holdings matrix, pairwise overlaps, unique top holdings). It is immediately distinguishable from get_security_holders and resolve_company, which it names explicitly.

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?

Gives an explicit routing rule: use get_security_holders when the question is one security across managers, and use resolve_company to resolve company identifiers. It also states the 2–6 investor bound and the period semantics (common quarter by default), so the agent knows exactly which tool answers which question.

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

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

Goes well beyond the readOnly/idempotent/non-destructive annotations: discloses the return payload (definitions, units, currency, missing reasons, derivation, source links), the period bases returned, pagination continuation mechanics (nextOffset, resultContinuations), identifier normalization with resolvedTicker echo, metric alias resolution with resolvedMetrics echo, and the shape of the error case with up to five candidate companies.

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?

Front-loaded with the purpose and the key sibling distinction, and most sentences carry unique routing or parameter information. It is a dense single block, though, mixing return contents, error recovery, aliasing and valuation workflow, which makes it harder to scan than bulleted sections would be.

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 10 parameters and no output schema, the description carries the burden of explaining return shape, period bases, pagination and error behavior — and it does all of that. Nothing an agent needs to invoke this correctly (identifier forms, metric selection, recovery args) is missing.

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 coverage is 90%, so the baseline is 3; the description adds real value by documenting an alias table (cash_and_equivalents→cash, fcf→free_cash_flow, etc.) that is not in the schema, plus the intent of 'metrics' (keep the answer focused) and 'limit'/'periodType' (control period count and basis). It leaves compact, from/to, offset and resultPath/resultOffset entirely to the schema, so it doesn't fully compensate.

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 verb and resource ('Get reported financial metrics ... from XBRL filings, by period') and enumerates the metric families covered, so an agent knows exactly what comes back. It explicitly distinguishes itself from the sibling read_statement ('use read_statement for other reported table values').

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?

Gives explicit routing rules: this tool for standardized metrics, read_statement for other reported table values, and list_statements → read_statement when balance-sheet metrics are unavailable. It also names the fallback path for unresolved tickers (resolve_company via repairable error) and states a hard prohibition ('Never state a figure from memory or infer it from a summary').

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

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

Annotations cover the read-only/idempotent profile, and the description adds substantial context on top: other forms are listed only, text access is restricted to periodic filings, unknown identifiers produce a repairable error with up to five resolve_company candidates, and ticker variants are normalized with resolvedTicker echoed.

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 purpose is front-loaded and nearly every sentence carries operational information. It is a dense single block, though, and the valuation-conclusion instruction sits slightly apart from what the tool itself does.

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 carries the burden and does so: it spells out the periodic response structure (headline, tl;dr, highlights, changes, watch items, per-section bullets and (part, sectionId) address) and states the exclusion of raw text explicitly.

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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema — that accession must come from list_company_filings and what omitting it does, plus concrete ticker-variant normalization behavior. It says nothing about resultPath/resultOffset beyond the schema's own overflow notes.

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 names the exact resource (8-K/6-K event summary, DEF 14A proxy extraction, 10-K/10-Q/20-F summary) and enumerates the returned fields, so an agent knows precisely what it gets. It also distinguishes itself from read_filing_section by stating full text lives there, not here.

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?

Explicit branching: supply an accession from list_company_filings for events/proxies, omit it for the latest periodic filing, and use read_filing_section for raw text. It names the prerequisite sibling and the alternative in the same breath, leaving nothing to inference.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description goes far beyond them: price-plausibility exclusion rules for USD totals, the precise meaning and December 2022 origin of the 'discretionary' checkbox, Form 144 as intent-only with no dollar contribution, 'not yet reported' semantics, and the repairable-error/candidates behavior. This is exactly the operational context an agent needs to avoid misreporting.

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?

Purpose is front-loaded in the first sentence, which is good. But the body is a dense, run-on wall of presentation doctrine and edge-case rules mixed with output semantics; several sentences (e.g. the repeated 'do not add caveats' and 'no verdict' instructions) restate the same stance and could be compressed.

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?

There is no output schema, so the description carries the full burden of explaining return semantics, and it does: row grouping by reporting-owner CIK set, no attribution to individual co-filers, USD totals that exclude failed-price rows, and continuation handling. An agent has everything needed to call this and interpret the result correctly.

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 coverage is 100%, so baseline is 3, but the description adds real meaning: the two views are distinct populations bucketed by filed role class (not by name), and company identifiers accept verified share-class variants and echo resolvedTicker. It adds little beyond the schema for window, resultPath and resultOffset, which keeps it from a 5.

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 opening sentence names a specific verb and resource ('Section 16 insider activity over a window') and enumerates the payload (summary figures, buyers/sellers, recent filings), plus an anchoring analogy ('the Insiders tab of a security page'). It does not, however, explicitly distinguish itself from close siblings like get_insider_transactions or screen_insider_activity, so the 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 gives strong guidance on how to interpret and present results (no caveats, no bullish verdicts, don't present failed rows as prices) and clarifies that the two views are different populations. It never says when to choose this tool over get_insider_transactions or screen_insider_activity, so selection guidance is only implied by scope.

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

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

With annotations covering read-only/idempotent/non-destructive, the description adds extensive behavioral detail beyond them: pagination with nextCursor, intra-filing resumption via transactionsSkipped/transactionsRemaining, price plausibility rules, 10b5-1 checkbox semantics back to December 2022, one-filing-group-per-call behavior with candidates, and holdings vs transactions separation. This is unusually rich and directly actionable.

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 a single enormous paragraph with many semicolon-separated clauses, making it difficult to scan. It front-loads the core purpose, but the volume of caveats and meta-instructions (e.g., 'do not explain this rule to the user unless asked') hurts conciseness. Structure is poor despite information density.

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 7 parameters, no output schema, and complex data, the description covers return shapes (positionAfter, valuePlausible, transactionsSkipped), error recovery (candidates, resultContinuations), and critical caveats (price check exclusions, derivative vs common shares). It leaves no major gap for an agent to call the tool correctly.

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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema for the reporter argument (token matching, punctuation/case handling, reporterKey preferred) and company identifiers (verified share-class variants, resolvedTicker echo, repairable error with resolve_company candidates). It adds less for other parameters, but the extra meaning is substantial.

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 opening sentence states a specific resource (one filing group's Form 4 filings at a company) and what is returned (transaction lines, latestReportedHoldings). It distinguishes itself from get_insider_activity by positioning itself as the drill-down. However, the purpose is buried in a dense, run-on sentence that requires careful parsing.

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?

Explicitly says to use it after get_insider_activity to open one row of 'who bought and sold', giving clear context. It also explains how to handle multiple candidates and the reporterKey alternative. It does not state when not to use it or name other alternatives, but the primary usage path is clear.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses that pages are byte-bounded rather than purely limit-driven (default 20, max 100 requested rows), that callers must follow nextOffset with identical slug/period/filters, that adjustment_note must be repeated when present, and that nested overflow requires resultPath/resultOffset recovery. That is substantially more than the annotations carry.

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?

Four front-loaded sentences with no filler; the returns/pagination contract arrives immediately after the purpose. Slightly terse in spots ('Repeat adjustment_note when present') where a few more words would aid first-time comprehension.

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 7-parameter, read-only, non-destructive tool with full schema coverage and no output schema, the description covers scope, filters, paging, and overflow recovery. It does not explain the result row shape or the units behind the reported percentages, which is the only material gap.

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 already explains slug, limit, offset, period, changeType and the resultPath/resultOffset recovery pair. The description reinforces the pagination-consistency constraint but adds no new format or syntax detail beyond what the schema states, so the baseline 3 applies.

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 verb and resource ('Get an investor's buy/sell activity for a specific period') and enumerates what the rows contain: new positions, increases, decreases, exits, with split-adjusted share changes and percentages. This implicitly separates it from holdings-oriented siblings like get_investor_holdings and get_position_history, but it never names an alternative, so it stops short of the 5 tier.

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?

'Can filter by change type' and the period parameter imply when the tool applies, but there is no explicit when-to-use vs when-not, and no routing to siblings such as get_investor_periods (to discover valid periods) or get_position_history. The agent must infer the workflow.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds value beyond them by disclosing the default page size (30), the default period fallback, and the continuation loop with nextOffset.

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?

Four short sentences, each carrying distinct information, with purpose and return shape front-loaded and defaults/pagination trailing. No filler; only the resultPath/resultOffset recovery path goes unmentioned.

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 compensates by listing the returned fields (shares, value, weight %, ticker, security details). The only omission is the nested-overflow recovery via resultPath/resultOffset, which an agent must infer from the schema alone.

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 coverage is 100%, so baseline is 3. The description earns a bump by explaining the pagination contract (reuse offset with the same filters) and that sort supports limiting top positions, clarifying behavior the schema fields only hint at.

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?

Opens with a specific verb and resource ('Get an investor's portfolio holdings for a specific period') and enumerates the returned fields, which distinguishes it from list-only siblings. It never names a sibling directly, so the differentiation is inferred rather than stated.

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?

Gives two concrete usage rules: omit period for the latest, and follow nextOffset with identical filters to continue. It offers no guidance on when to choose this over get_position_history, get_investor_summary, or get_investor_activity, which is the main gap.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds real behavioral value beyond them: result ordering (most recent first) and the fallback that ambiguous identifiers return candidates rather than erroring or guessing.

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, zero filler, with the core purpose and ordering front-loaded before the identifier detail. Nothing could be removed without losing information.

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?

No output schema exists, but the description conveys enough (a list of reporting periods, newest first) to know what comes back, and the schema fully covers pagination recovery. A brief note on what a 'period' is (quarterly/annual) would close the remaining gap.

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 already documents slug formats and both continuation parameters. The description's abbreviation examples largely restate the slug schema and say nothing about resultPath/resultOffset recovery semantics, so it adds little beyond structured data.

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 verb and resource ("Get all available reporting periods for an investor") plus ordering (most recent first), which clearly separates it from siblings like get_investor_summary or get_investor_holdings. It does not name a sibling explicitly for differentiation, but the resource boundary is unambiguous.

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 second sentence explains identifier flexibility and fallback behavior for unknown/ambiguous slugs, which is useful input guidance. However, it never says when to call this versus alternatives such as list_statements or get_investor_summary, so usage is only implied.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered; the description adds real business logic instead — the derivatives block is 13F reported (usually notional) and must never be added to totalValue or used to derive combined weights. It doesn't mention the resultContinuations/overflow behavior beyond what the schema documents.

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?

Front-loaded with the payload, then the derivative caveat, with no filler sentences. The derivatives sentence is long and clause-heavy, but every element of it prevents a real aggregation error, so it earns its space.

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?

No output schema exists, and the description compensates by describing the returned fields and the separate labelled derivatives block. For a 4-parameter read tool with full schema coverage and explicit annotations, an agent has everything needed to call it and interpret the result.

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% and the slug description already spells out CIK, slugified name, and prefix matching, so the description adds nothing about parameters. The only adjacent guidance is the implicit 'omit period for latest' already stated in the schema, leaving this at the baseline.

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?

Specific verb plus resource, and it enumerates the exact payload (stock total value, position count, top 5 holdings, concentration metrics). It also carves out a distinct scope from get_investor_holdings by framing itself as the lightweight/overview path, so an agent can separate it from its siblings without opening 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?

Explicitly says to use this 'for quick overview questions instead of fetching all holdings,' which gives both a condition and the alternative category. It doesn't name get_investor_holdings or get_investor_periods directly, and says nothing about when period resolution is needed, so it falls short of a full when/when-not rule set.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral instructions about repeating adjustment_note and following nextOffset to continue, but it does not explain what adjustment_note represents or how resultContinuations overflow recovery behaves.

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 overall purpose, then moves efficiently through view semantics and pagination. It is reasonably tight, though the pagination sentence slightly duplicates the offset schema description.

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 present, the description helpfully outlines what each view returns, including buyer/seller counts and top position changes, and it mentions adjustment_note and nextOffset continuation. It still leaves resultPath/resultOffset overflow recovery largely to the schema, which is a minor gap given the tool's complexity.

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 all six parameters are already well documented in the schema, including view, limit, offset, period, resultPath, and resultOffset. The description restates view meaning and pagination behavior but adds no format or syntax details beyond the schema, making 3 the appropriate baseline.

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 names a specific verb and resource ('Get a market-wide overview of recent activity among tracked investors') and defines what each view returns. It does not explicitly contrast itself with nearby siblings such as get_investor_activity or get_insider_activity, so an agent must infer the broad-market scope, but the core purpose is clear.

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 clearly explains the two view modes ('by_security' for trending stocks, 'by_investor' for per-investor activity) and gives pagination guidance. However, it does not state when to choose this tool over adjacent siblings, nor does it provide exclusions or required preconditions.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavior: byte-bounded pages with a sane default of 20 and a 100 request ceiling, the nextOffset follow-up rule, ticker normalization with resolvedTicker echo, and unknown identifiers producing a repairable error with resolve_company candidates. That is the kind of operational detail an agent cannot get from the annotations.

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?

Dense but mostly front-loaded: purpose and return contents come first, then pagination, then the usage example, then identifier handling and error recovery. The usage example arriving after the paging mechanics is slightly misplaced, and the identifier-variant enumeration is verbose, but no sentence is pure filler.

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?

No output schema exists, yet the description enumerates the return fields and the activity-type vocabulary (NEW, INCREASED, DECREASED, SOLD, UNCHANGED), so an agent knows what comes back without a schema. With 6 parameters (2 required) fully documented at 100% schema coverage plus annotations, nothing material about invoking it correctly is missing.

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 coverage is 100%, so baseline is 3; the description earns a bump by explaining normalization semantics for tickerOrCusip (BRK-B/BRK/B/BRK B/brk.b → BRK.B, resolvedTicker echo) and by confirming the limit/offset paging contract and the repairable-error recovery path. The nested resultPath/resultContinuations overflow arguments are only gestured at ('follow nextOffset') rather than explained, which keeps it from a 5.

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?

A specific verb + resource + scope: 'Track how a specific investor's position in a security has changed over time', and it names the exact data returned (shares, value, delta/percentage, activity type, adjustment_note). The 'over time'/'chronological timeline' framing implicitly separates it from snapshot siblings like get_investor_holdings, but no sibling is named, 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?

It supplies a concrete usage question ('How has Buffett's AAPL position changed over the years?') that pins down the intended call context and the two required identifiers. It gives no explicit exclusions or named alternatives (e.g. use get_investor_holdings for a current snapshot), so the routing guidance stops short of a 5.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, yet the description still adds genuinely new behavioral detail: identifier normalization rules, the resolvedTicker echo, and that unknown identifiers produce a repairable error carrying up to five resolve_company candidates. That error contract is the kind of context annotations cannot express.

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?

Front-loaded with what the tool returns, then identifier rules, then error behavior — a sensible ordering with no filler sentences. It is denser than average, but each clause carries distinct information rather than restating the name or annotations.

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 present, the description must convey return content, and it does so by enumerating the three data sections; pagination recovery is delegated to the well-documented resultPath/resultOffset parameters. It stops short of describing the output shape or how the sections are keyed, which for a no-output-schema tool leaves a small residual gap.

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 coverage is 100%, so baseline is 3, but the description goes beyond the schema's terse 'Stock ticker (e.g. AAPL, GOOGL)' to specify verified share-class variant forms (BRK-B, BRK/B, BRK B, brk.b → BRK.B) and the resolvedTicker echo. The period and pagination parameters are left entirely to the schema, which is acceptable given its coverage.

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 verb and resource ('Get detailed information about a security') and enumerates the three payload areas: current owners with share counts and values, quarterly ownership history, and recent buy/sell activity. It is clear what the tool returns, but it never contrasts itself with the close sibling get_security_holders, so the agent must infer the boundary itself.

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?

Usage is only implied: the description says what data comes back, from which an agent infers 'use this when you need a full security profile'. There is no explicit when-to-use, when-not-to-use, or alternative-naming guidance despite several overlapping siblings (get_security_holders, get_position_history, get_investor_holdings). The ticker-variant and error-recovery notes are input guidance, not tool-selection guidance.

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

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

Beyond the read-only annotations, it discloses important behavior: totalCount includes exits before paging, population counts precede changeType filtering, exits and family aggregate totals are included, tie-breaking rules for portfolioRank, portfolioWeightPct scope, and resultContinuations overflow recovery. These details materially reduce ambiguity about what the returned counts and rows mean.

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 front-loaded, starting with the primary purpose and then covering filtering, counts, pagination, and error recovery. Most sentences carry useful information, though the single-paragraph format makes the density slightly harder to scan than an ideally structured description.

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 complex read-only tool with eight parameters and no output schema, the description explains return semantics, count behavior, pagination, identifier normalization, and error repair. It provides enough information for an agent to invoke the tool correctly and interpret the main returned values.

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 coverage is 100%, so the baseline is already strong, but the description adds meaningful semantics for changeType filtering order and scope, ticker normalization variants, slug family aggregate representation, and period default behavior. It does not need to repeat every schema detail, but it usefully clarifies the most error-prone inputs.

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: showing tracked investors who hold a security, along with the exact data fields returned. It also implicitly distinguishes this per-security holder view from sibling investor-centric tools such as get_investor_holdings, so an agent can identify the correct tool without opening 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 usage context: optional investor slug and period restrictions, resolve_company for identifier resolution, and continuing via nextOffset with identical filters. It also clarifies that changeType is a per-security row filter rather than a screener filter, though it does not explicitly compare this tool against every sibling alternative.

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

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

Annotations already cover readOnly/idempotent safety, and the description adds the operational detail they can't: newest-first ordering, which form types get full text vs. AI summaries vs. proxy extractions vs. metadata-only, the nextOffset/resultContinuations pagination contract, and repairable error behavior with up to five resolve_company candidates. That is a substantial disclosure load beyond the structured fields.

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?

Front-loaded with the highest-value facts (ordering and returned fields) and free of filler, but the remaining rules are packed into an undifferentiated run of sentences. A short bulleted split of filtering, pagination and identifier rules would scan faster, though nothing is genuinely wasted.

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?

No output schema exists, so the description must convey the return shape, and it does so field by field. Filtering, pagination, identifier normalization and error recovery are all covered, leaving nothing an agent needs in order to call it correctly.

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?

With 67% schema coverage and no description at all on limit/offset, the description carries real weight: it explains formTypes exact-match/default semantics, the ticker normalization rules (BRK-B, BRK/B, BRK B → BRK.B) and resolvedTicker echo, and how resultPath/resultOffset continuation works. It stops short of stating the default page size or the 30-row ceiling on limit.

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?

Opens with a specific verb and resource ('List company filings') plus sort order and the exact payload fields (accession, items, AI headline, hasSummary, hasText, hasStatements, sourceLink). That is enough to separate it from search_disclosures, get_filing_summary and read_filing_section without opening a 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?

Clearly states the default form universe (10-K/10-Q/20-F, 8-K/6-K, DEF 14A incl. amendments) and the when-to-use rule for formTypes, plus that other forms like 424B4/S-1 are listed only when requested. It also escalates unknown identifiers to resolve_company, but it never contrasts itself with sibling tools such as search_disclosures or get_filing_summary.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile costs the description nothing. It adds real value beyond that: default 50 / max 100 byte-bounded pages, nextOffset follow-up, the 75%-coverage consensus-quarter fallback, and the caution that firm 13F and fund N-PORT must never be summed. Those are substantive behavioral disclosures that lift it above a bare 'list' verb, though the pagination guidance largely restates the schema.

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?

Front-loaded with the core purpose and each sentence carries information — the consensus-quarter and fund-family sentences materially affect interpretation. It is dense and slightly redundant with the schema on pagination mechanics, costing it the top mark.

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?

No output schema exists, so the description must describe the response, and it does: latest portfolio period, total value, position count, consensus stats, nextPeriod {period, investorsFiled}, fundCount/funds, plus the pagination continuation contract. An agent can call and interpret this tool without further context.

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 coverage is 100% with per-parameter descriptions for limit, offset, resultPath, resultOffset and the investor_style enum, so the schema already does the heavy lifting. The description adds the default of 50 rows, the 100-row ceiling, and that investor_style is available on every plan — marginal but genuine value. 3 reflects the baseline where the schema is authoritative.

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 verb and resource (list tracked superinvestors) and enumerates what each row carries: primaryStyle, latest portfolio period, total value, position count, plus consensus stats. The fund-family/firm dedup clause and the 13F vs N-PORT warning make the scope unmistakable versus the many get_investor_* and screen_* 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?

"Use this to see who is being tracked or for dashboard-level questions" gives a clear selection context, and the drill-down note about fund slugs points toward the detail tools. It stops short of naming an explicit alternative (e.g. get_investor_summary) or a when-not-to-use condition, so it does not reach 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world. The description adds real behavioral context beyond that: independence from AI summaries, pagination via nextOffset, ticker normalization with resolvedTicker echo, and a repairable error path with up to five candidates.

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?

Four compact sentences, each carrying distinct information: scope, return shape, independence from summaries, and pagination/error/normalization behavior. Front-loaded and free of filler.

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 supplies the return fields and continuation mechanics, plus error recovery and ticker normalization. Minor gaps remain around limit defaults and the relationship between nextOffset and the offset parameter, but nothing critical to correct invocation is missing.

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 coverage is 71%, so the schema covers much of the ground. The description still adds meaningful semantics for the ticker parameter (share-class variant normalization) and pagination follow-through that the schema does not fully convey.

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 verb and resource: discovering primary statements, notes, and detailed tables in one published filing, and enumerates what is returned (statement IDs, names, source links). This is clearly distinguishable from read_statement (reads content) and list_company_filings (lists filings).

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 scope ('one published filing') and required accession imply the workflow, and the description routes unknown identifiers to resolve_company candidates. It does not explicitly name sibling alternatives or exclusions, so it falls short of a 5.

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

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

Beyond the read-only annotations, it discloses paging behavior (~12,000 characters), nextOffset continuation, missing-section behavior returning availableSections, find semantics including found:false and suggestions, offset indexing, ticker normalization, and repairable error behavior. This is unusually rich operational context with no contradiction of annotations.

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 purpose and grounding rule are front-loaded, and every sentence carries useful operational detail. It is dense and somewhat long, with some overlap between the find/offset prose and schema descriptions, but the length is largely justified by the tool's complexity.

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 complex, 8-parameter read tool with no output schema, the description covers the important return and continuation behaviors: page size, nextOffset, missing sections, find results, and error recovery. Nothing an agent critically needs in order to call it correctly appears absent.

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 coverage is 100%, so the baseline is 3, but the description adds real meaning: sectionId aliases, ticker normalization variants, offset continuation, and the optional literal find behavior with suggestions. It stops short of exhaustively explaining resultPath/resultOffset, but adds substantial value beyond the schema.

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 verb and resource ('Read the raw text of one filing section') and explicitly distinguishes itself as the grounding tool versus get_filing_summary and search_filing_text. An agent can immediately tell what it returns and why it exists.

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?

Gives explicit when-to-use guidance: verify or quote filing language before factual claims, source identifiers from get_filing_summary or search_filing_text, and read Risk Factors/MD&A before downgrading a claim. It also names the alternatives that supply the required accession/part/sectionId.

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

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

Annotations already declare readOnly/idempotent/closed-world, and the description still adds substantial behavior beyond them: pagination via rows and columns, nextTextOffset/nextFootnoteOffset continuation protocol, budgeting text with rowIds: [], the empty-cell-plus-non-null-offset recovery path, ticker normalization with resolvedTicker echo, repairable errors with up to five resolve_company candidates, and a data-integrity warning against summing unlike units or quarterly vs cumulative periods.

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?

Purpose leads, then continuation mechanics — a sensible front-load with no filler sentences; every rule maps to a real failure mode an agent would hit. It is dense to the point of being packed into one paragraph, which slightly hurts scanability for a 14-parameter tool.

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 14-parameter paginated reader with no output schema, the description covers what comes back (raw numbers, scale, unit, period, dimensions, links) and how to keep paging, plus error/identifier edge cases. The remaining gaps (simple limit/offset semantics) are low-risk and partly documented in the 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?

With only 36% schema coverage across 14 parameters, the description does real work: it explains rowIds/columnIds as cell targeting, textOffset/nextTextOffset and footnoteOffset/nextFootnoteOffset pairing, and preserves the 'column_limit' spelling. It leaves limit, offset, columnOffset and statementId's provenance largely to inference, so it is not fully compensating.

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?

Names a specific verb and resource ('Read structured filing rows and cells') and enumerates the returned payload — raw numbers, display scale, unit, period, dimensions, source links. That scope cleanly separates it from list_statements (enumeration), read_filing_section (prose) and get_company_financials (Core metrics).

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?

'Use for numbers absent from Core and to explain the selected statement' gives a concrete selection condition, and the continuation rules (textOffset, footnoteOffset, rowIds/columnIds targeting, empty-cell retry) tell the agent exactly how to proceed on follow-up calls. It stops short of naming a sibling alternative by name for the borderline cases (e.g. when to prefer search_filing_text for narrative).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the shape of the result (including has-financials and has-filing-text flags) and the continuation protocol ('Follow nextOffset as offset with the same filters'). It does not explain the nested resultPath/resultContinuations overflow case, which is the least obvious 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?

Three sentences, zero filler, and the sequencing instruction ('use this FIRST') is front-loaded immediately after the purpose statement. Every clause carries actionable information.

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 compensates by naming the returned fields and the pagination follow-up, which is enough to call and continue correctly. It stops short of saying what to do when resolution yields multiple candidates or no match, a real decision point for a resolver tool.

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 coverage is 100%, so the baseline is 3 and all five parameters are already documented. The description reinforces the offset continuation contract ('same filters') but says nothing about includeInactive or the resultPath/resultOffset recovery mechanics, so it adds only marginal meaning beyond the schema.

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 verb and resource ('Resolve a company name or ticker to candidate companies') and enumerates the return payload (ticker, name, CIK, financial-data/filing-text flags). It is clearly distinguishable from siblings like get_company_financials or list_company_filings, which consume the output of this tool rather than produce the identifier.

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?

'Use this FIRST when the user names another company (e.g. 'Microsoft', 'compare with MSFT') to get the ticker before calling the other filing/financials tools' gives an explicit ordering rule, a trigger condition, and names the dependent tool family. No ambiguity about when to reach for this versus a lookup-only sibling.

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

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

Annotations only cover read-only/idempotent safety, and the description adds substantial non-obvious behavior: USD totals exclude pricePlausible=false rows while unverifiable prices still count, 'discretionary' vs 10b5-1 semantics with a Dec-2022 checkbox cutoff, and a hard cap of 25 companies plus total count. Null-price and withheld-market-cap behavior (deliberate refusal, quote the reason) are disclosed rather than left to guess.

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 purpose is front-loaded, but the body becomes a long undifferentiated wall of field-level rules (priceVsRef, marketCapBasic, sharesObservedAt, sharesClassScope, marketCapBasis, marketCapWithheldReason, clusterBuyers) plus style directives. Much of this belongs in a return-value reference or in per-field guidance rather than a single prose block. Length and density make it hard to parse even though most sentences carry real information.

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, zero-required, no-output-schema tool, the description covers what comes back (ranking, per-company buyer detail, priceVsRef, latestClose nulls, market-cap basis and withheld-reason strings, 25-row cap plus total count) and how paging works via cursor/resultPath. Nothing an agent needs to call and interpret it is missing.

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 coverage is already 100%, so the baseline is 3. The description still adds interpretive meaning beyond the schema: it explains that 'discretionary' reflects the filing checkbox rather than a 10b5-1 plan and that unanswered checkboxes are 'unknown', and it ties minValue to plausible-price totals. It does not, however, explain preset interactions or the cursor/resultPath overflow mechanism, which the schema hints at.

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 concrete verb and resource (site-wide insider screener at /insiders ranking companies by insider flow) plus the output dimensions (who bought, what they paid, current price). It explicitly differentiates from the sibling get_insider_activity by scope: many companies vs one named company.

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?

Gives an explicit use case ("which companies are insiders buying") and an explicit exclusion naming the correct alternative (get_insider_activity) for the single-company case. It also constrains response style (no verdicts, no disclaimers), which shapes invocation expectations.

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

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

Annotations already cover read-only/idempotent safety, but the description adds material context they cannot: sortBy is available on every plan including free and anonymous/demo, counts and dollars are recalculated from only the requested styles, and pagination continues via nextOffset with identical filters. Those are non-obvious behavioral traits an agent would otherwise get wrong.

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?

Five dense sentences, all front-loaded with the screening purpose and ranking before the sortBy guidance. Every sentence carries information, but the sortBy discussion is compressed into one long clause chain that slightly hurts scanability.

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?

Covers the tricky parts of a 9-parameter screening tool with no output schema: ranking semantics, plan availability, style-scoped recalculation, and both pagination mechanisms (nextOffset and resultPath overflow). It omits what a result row contains, which the absence of an output schema leaves unaddressed.

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 coverage is 78%, so the baseline is 3, and the description earns above that by explaining what each sortBy value actually ranks and that 'side: sell' reverses the default score. It also clarifies offset/nextOffset continuation and lists valid investor_style keys, though it leaves min_investors and limit defaults to the schema.

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 verb and resource plus scope: 'Screen stocks by material quarterly activity among tracked investors'. The default ranking formula (2*NEW + INCREASED - DECREASED - 2*SOLD) makes the result semantics concrete and separates it from list-style siblings like get_security_holders or get_investor_holdings.

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?

Gives concrete selection guidance for the ordering decision: 'Use sortBy: buyers to answer which stocks did the most funds buy/add', and explains what sellers and net_value rank. It does not explicitly exclude or name sibling tools as alternatives, so it falls short of a full when/when-not map.

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

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

With annotations already covering read-only, idempotent, non-destructive, and closed-world behavior, the description adds substantial behavioral context: returned investor fields, role definitions for firm/fund/investor, parentSlug semantics, owner counts on security matches, and the one-character investor-skip rule. These details materially help an agent predict results and edge cases.

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 front-loaded: the first sentence states what can be searched, and subsequent sentences cover matching rules, return semantics, selection behavior, and pagination. Every sentence appears to earn its place, with no obvious repetition of annotations or schema text.

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?

Although there is no output schema, the description explains what investor and security matches carry, including roles and owner counts. Combined with rich annotations and a fully documented parameter schema, it gives an agent enough information to call the tool correctly and interpret the main results.

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 coverage is 100%, so the schema already documents all four parameters and sets the baseline at 3. The description still adds meaningful query semantics beyond the schema: the two-character minimum for investors, the one-character security exception, how names/tickers map to firms or funds, and how nextOffset continues the search.

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 gives a specific verb and two concrete resources: investors by name, manager, slug, fund ticker, or alias, and securities by ticker or issuer name. It also positions the tool as a slug/ticker resolver before detail lookups, which separates it from the get_* detail siblings and from filing-text search 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?

It explicitly says to use this tool to find the correct slug or ticker before looking up details, and it explains the continuation pattern with nextOffset. It does not name alternatives such as list_investors or resolve_company, nor does it state when not to use search, so it falls short of full when/when-not guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive, so the safety bar is met; the description adds genuinely non-obvious behavior: bounded snippets with read_statement coordinates and source links, per-report nextMatchOffset continuation and resultPath overflow recovery, ticker normalization with resolvedTicker echo, and a repairable error returning up to five resolve_company candidates. Minor deduction because the nextMatchOffset vs nextOffset pagination sentences are slightly hard to disentangle and limit behavior is never mentioned.

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?

Purpose and scope are front-loaded, and nearly every sentence carries load (routing, caveat, pagination, error recovery). The two adjacent continuation sentences about nextMatchOffset and nextOffset are somewhat overlapping and cost a bit of clarity.

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 an 8-parameter, no-output-schema search tool this covers the important ground: what comes back, how to paginate, how overflow is recovered, and what errors look like. The unresolved pieces are the limit and offset parameters, which are neither documented in the schema nor the description.

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 coverage is 63%, so the description must do some lifting, and it does: it explains the intent behind accessions (one filing vs cross-period comparison), the matchOffset/nextMatchOffset pairing with the same page offset, and the resultPath/resultOffset overflow pattern. It never explains limit (1-8) or offset, which carry no schema description, leaving a real gap.

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 verb (search) plus exactly what is searched (structured notes, row labels, text cells, footnotes) and the matching mode (English literal substring). It explicitly separates itself from the narrative-text sibling by naming search_filing_text, so an agent can pick the right tool without opening either 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?

Gives the operating envelope (1-3 company-owned accessions, single filing vs cross-period comparison) and an explicit exclusion routing narrative chapters to search_filing_text. It also states a use-condition caveat: read source reports before making claims or comparing figures, and no match never proves absence.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses the ranked-snippet return shape, the '[Separate passage]' compatibility separator warning, nextOffset chaining, resultContinuations overflow recovery, ticker normalization with resolvedTicker echo, and the repairable-error behavior with up to five resolve_company candidates. This is unusually rich behavioral context for a read tool.

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?

Front-loaded with purpose and return shape, then caveats and routing. Dense but each sentence carries distinct operational information; only the compatibility-separator sentence is slightly granular for its position.

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 6-parameter search tool with no output schema, the description covers returns, pagination, overflow recovery, identifier normalization, and error remediation. An agent has everything needed to call it, chain it, and recover from failures.

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 coverage is 100%, so baseline is 3; the description still adds value by explaining ticker variant acceptance and normalization, the accession scoping semantics, offset chaining through nextOffset, and that query should use concrete filing terms. It does not mention resultPath/resultOffset beyond what the schema already says, which keeps it below a 5.

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 verb and resource: 'Full-text keyword search over a company's filing sections,' then describes exactly what comes back (ranked matches, snippets[], accessionNumber/part/sectionId). It explicitly distinguishes itself from read_filing_section and get_company_financials, so an agent can pick it without opening sibling schemas.

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?

Gives a positive condition ('locate where a topic or phrase is discussed when you don't already know the section'), names two alternatives with their selection conditions (read_filing_section for known phrases, get_company_financials for numeric values), and adds an optional narrowing path via accession. Nothing is left to inference.

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