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

Annotations already declare readOnlyHint=true and openWorldHint=true, indicating it's a safe read operation. The description adds useful behavioral context: it works on every tier and is free, and it's a snapshot of current usage. No contradictions with 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 description is two sentences with no wasted words. It is front-loaded with the core purpose and efficiently includes usage guidelines and alternatives.

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 no output schema, the description sufficiently explains the tool's output fields (plan name, requests today, daily limit, all-time count). It is complete for a simple snapshot tool with no parameters.

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?

There are no parameters (schema coverage 100% trivial), so baseline is 4. The description adds meaning by explaining what the tool returns (plan name, requests today, etc.), compensating for the lack of an output 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?

The description clearly states the tool provides a snapshot of the authenticated API key's current usage, listing specific fields (plan name, requests today, daily limit, all-time count). The verb 'check' matches the tool name and the resource is well-defined, distinguishing it from sibling tools like get_usage_history and get_key_activity.

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 explicitly says to use this for a quick right-now check and provides alternatives: get_usage_history for daily trends and get_key_activity for per-request logs. This gives clear when-to-use and when-not-to-use 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 only declare readOnlyHint and openWorldHint; the description goes well beyond them by disclosing that this is a LIVE, uncached reconstruction that can diverge from the stored signal after amendments, the Business-plan gating (402 PLAN_REQUIRED on Free/Starter/Pro), and the exact 404/400 failure modes. It does not spell out pagination or sizing of the returned evidence lists, but the safety and cost profile is fully covered.

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, then usage, then mechanics, and it is dense with no filler sentences. It is on the long side and the routing advice ('audit or debug a specific signal rather than scan') restates the earlier 'use this when' guidance, a mild redundancy.

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 tool with no output schema and thin annotations, the description carries the full load and does so: it enumerates what is returned (criteria, cluster buyers/sellers with roles and trades, exclusions and reasons, raw buy/sell totals), the plan requirement, and every error code. An agent has everything needed to call and interpret 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 coverage is 100%, so the schema already documents both parameters; the description's added value is contextual, explaining that ticker is taken directly (enabling the skip of a prior lookup) and that omitting date falls back to the most recent signal with a SIGNAL_NOT_FOUND on miss. That reinforces behavior but adds little syntax 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 ('Explain why a signal fired') and immediately enumerates the substance returned: the insiders and trades counted, what was excluded, and the criteria. It explicitly distinguishes itself from get_signals (finding which companies have signals) versus this tool (explaining one company's signal), so an agent can route without inspecting 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 explicit when-to-use conditions ('when the question is WHY a named company's signal fired, or WHICH insiders and trades made up its cluster') and an explicit when-not with the named alternative ('rather than to scan many companies (use GET /v1/signals for that)'). It also removes a prerequisite the agent might otherwise assume ('there is no need to call GET /v1/signals first').

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?

Description adds value beyond readOnlyHint and openWorldHint by specifying pagination (max 100/page), free plan, and the exact fields returned. No contradictions with 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?

Three concise sentences covering purpose, usage guidance, and pagination/free plan. No unnecessary words, highly efficient.

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?

Output fields are described, pagination mentioned. Lacks handling of edge cases like empty results or error conditions, but adequate for a list tool without output 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?

Schema coverage is 100%, so description does not need to add much. The description mentions 'given ticker' but adds no extra semantics beyond schema 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 clearly states the tool returns a full roster of insiders who filed Form 4 for a ticker, listing specific fields. It distinguishes from sibling tool get_transactions by noting it is for enumerating insiders before pulling career summaries.

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 states when to use this tool (to enumerate insiders before pulling career summaries) and directs to get_transactions for trade history, providing clear alternative 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 readOnlyHint=true and openWorldHint=true, so the description adds value by specifying 'Free plan' (implies usage limits) and listing returned fields. No contradictions; additional context enhances transparency.

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, front-loaded with purpose and fields, followed by usage guidance. No unnecessary words; every sentence earns its place.

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 simple tool with one parameter and no output schema, the description lists all returned fields and provides usage context. Lacks mention of limits or pagination, but not needed for single-ticker lookup. Adequately complete.

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% for the single parameter (ticker), so baseline is 3. The description doesn't add extra semantics beyond the schema, but it's adequate given the high 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?

The description clearly states it provides a company profile for a single ticker, listing specific fields (name, CIK, SIC, etc.). It distinguishes from siblings by explicitly naming get_company_insiders and get_transactions as alternatives for different purposes.

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 tells when to use this tool ('for company identity/metadata') and when to use alternatives ('use get_company_insiders to list who is filing, or get_transactions with ticker= for their trade history'). Clear and actionable 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 readOnlyHint/anomaly annotations, the description discloses live execution with no caching, the Pro plan requirement (402 on Free/Starter), and the 404 behavior when neither ID nor slug matches. These are valuable behavioral traits that the annotations do not already cover.

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 purpose and contains all necessary behavioral context in a compact two-sentence paragraph, but there’s a small redundancy: the pseudo‑'Requires Pro plan or higher' line repeats the parenthetical '(Pro plan+)' from the opening sentence. Still, overall structure and placement are excellent.

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 there is no output schema, the description clearly enumerates the required return data: identity fields, buy/sell trade counts, most recent disclosure date, top N tickers, and recent trades with their shape. It also covers error responses and plan restrictions, making the tool realistically callable end-to-end without additional assumptions.

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?

The input schema has 100% description coverage, so the baseline is 3. The main description adds marginal value by clarifying that 'most traded' is by trade count and that recent trades have a specific shared shape, but it does not materially change understanding of the three parameters beyond the schema 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 opens with a specific verb and resource: 'Get one politician's congressional trading profile.' It then enumerates the exact returned fields and differentiates the tool from paging /v1/congress/trades by framing it as a 'one-call politician overview,' which helps an agent distinguish it from siblings like list_congress_trades or get_congress_ticker_rollup.

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 directs agents with 'Use this for a one-call politician overview rather than paging /v1/politician= yourself.' This names the alternative approach and tells the agent when this tool is appropriate, satisfying both when-to-use and an alternative context.

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?

The description goes well beyond the readOnlyHint and openWorldHint annotations by disclosing plan gating, the PLAN_REQUIRED error on Free/Starter, the live no-cache behavior, the meaning of non-superseded trades, and the 200-with-empty-array behavior for tickers with no congressional trades. This is strong behavioral transparency.

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 appropriately detailed, covering return shape, edge cases, plan limits, and live behavior. It is not overly verbose, though the explanation about the absence of a separate ticker entity could have been tightened.

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 sufficiently explains the expected return shape, empty-ticker behavior, and access constraints. It could be even more complete by specifying exact response fields or boundary behavior, but it is enough for an agent to select and invoke 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?

The input schema already documents both parameters with 100% coverage, so the description adds little parameter meaning beyond repeating the trailing-window behavior for window_days. This matches the baseline of 3 when schema descriptions carry the semantic load.

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 clearly states the tool's purpose: it returns every politician who traded a given ticker, with per-politician trade counts and ticker-level totals. This is a specific verb-resource pairing that is semantically distinct from sibling tools like get_transactions or list_congress_trades.

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 parameter context, such as optional window_days behavior and Pro plan requirements, but it never explicitly tells an agent when to choose this tool over a sibling like get_congress_politician or list_congress_trades. It provides implied usage rather than direct routing 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 only cover readOnlyHint and openWorldHint, so the description carries real weight and delivers: plan gating with the exact error code, live uncached query behavior, caller-overridable clamps on window_days/lookback_days, exclusion of implausible congressional dates, and an explicit disclaimer that no alpha/win-rate is computed. This is behavioral context well beyond 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?

The core purpose and scoping are front-loaded, and the DEFINITION/HONESTY sections carry substantive return-value and disclosure semantics rather than filler. It is nonetheless a dense wall of ALL-CAPS prose with some repetition (e.g. the 'no predictive edge' point is made twice), which costs 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?

With no output schema, the description fully documents the return shape: insider.signalDate, insider.insiderCount semantics, the congress leg set, firstSeen/lastSeen, the strength multiplication formula, amountLow/amountHigh ranges, disclosureLagDays, and dateQuality being null. Nothing an agent needs to interpret results 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 description coverage is 100%, so the schema already documents page, per_page/limit, ticker, window_days and lookback_days including their defaults, bounds and the alias rule. The description largely restates those (e.g. the alias and clamp notes), adding only marginal meaning, so the baseline 3 is appropriate.

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 precise compound resource (insider cluster-buy x congressional-purchase convergence) with the exact qualifying conditions, immediately distinguishing it from siblings like get_signals, get_key_activity and get_insider_transactions. An agent can tell what this tool returns without opening any 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 clear context for use (detection/monitoring of disclosed insider AND congressional buying, not predictive edge) and a hard prerequisite (Pro plan+, 402 PLAN_REQUIRED on Free/Starter). It does not, however, explicitly name an alternative sibling or state when NOT to use it versus get_signals.

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 and openWorldHint. The description adds valuable context: caching for 30 minutes, no API key required, and a detailed list of returned metrics. This goes beyond the annotations without contradicting them.

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 well-structured, starting with purpose, then usage guidance, then a bulleted list of included metrics, and finally caching/auth notes. It is slightly long but every sentence adds value.

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 no output schema, the description provides a comprehensive list of what is returned (timestamps, latencies, counts, percentages) and context on caching and public access. The tool is simple and the description fully explains its behavior and output.

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?

The schema has zero parameters and the description explicitly confirms 'Takes no parameters', adding certainty. With no parameters, the baseline is 4, and the description fulfills that.

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 clearly states the tool returns public data-quality metrics for the whole dataset, using specific verbs like 'returns' and 'use this to check'. It distinguishes itself from sibling tools by explicitly stating it is not for looking up individual companies or transactions.

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 provides clear when-to-use guidance ('check whether the dataset is current before relying on it') and what not to use it for ('not to look up any single company'). It mentions it's public and needs no API key, but does not explicitly name alternative sibling tools.

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 indicate readOnlyHint and openWorldHint. Description adds return fields (dates, identity, transaction count) and free plan mention, but lacks details on error behavior or limitations.

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 sentences, front-loaded with purpose and example, concise with no unnecessary words.

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 1 param and no output schema, description covers what is returned and when to use. Could mention missing accession handler but sufficient for 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 description. Description adds format example (0000320193-26-000001) and context to copy from other tools, exceeding the schema's base description.

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?

Clearly states it fetches a Form 4 filing by accession number, with format example. Distinguishes from siblings like get_recent_filings and get_transactions.

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 'Use this once you already have an accession number from get_recent_filings or get_transactions', providing clear when-to-use and source of input.

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?

Despite annotations already providing readOnlyHint and openWorldHint, the description adds valuable behavioral context: timing (2 days before Form 4), pagination (max 100/page), and the signal nature (discretionary vs 10b5-1). No contradiction with 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?

Every sentence adds value: purpose, timing, filtering, cross-reference, plan requirement, pagination. No wasted words, well-structured and front-loaded.

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 core purpose, filtering, usage advice, complementary tools, and restrictions. Lacks explicit output fields, but given no output schema and common knowledge of Form 144, it is sufficiently complete for an experienced agent.

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 adds marginal value by advising use of exclude_10b5 for signal analysis and clarifying date range and partial match on insider name, but mostly reiterates schema 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 clearly states the tool retrieves Form 144 'notice-of-proposed-sale' filings, explaining they are early-warning signals for insider sales. It distinguishes from siblings like get_transactions by suggesting cross-referencing to check execution, and specifies filtering options.

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 guides when to use (early-warning signal) and when to use alternatives ('Cross-reference with get_transactions/get_insider_transactions'). Also recommends excluding 10b5-1 for signal analysis and notes 'Requires Business plan' as a usage restriction.

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 declare readOnly and openWorld hints. Description adds pagination limit (max 100/page) and plan requirement, which are useful behavioral details beyond 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?

Three sentences, no redundancy. Efficiently conveys resource, filters, use cases, sibling associations, and constraints (plan, pagination).

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 read-only tool with good schema and no output schema, description adequately covers functionality, filtering, pagination, and plan requirement. Missing return format details but acceptable.

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 covers all 7 parameters with descriptions (100% coverage). Description adds context like 'CUSIP resolved to ticker automatically' but mostly summarizes, not adding significant new semantics beyond 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?

Description clearly states the tool returns institutional 13F-HR holdings with filtering options. It gives concrete use cases ('who owns NVDA') and distinguishes from siblings like get_managers and get_transactions.

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?

Provides examples of when to use and pairs with siblings for further lookups. Mentions plan requirement. Lacks explicit when-not-to-use but context 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?

Annotations already declare readOnlyHint=true and openWorldHint=true. Description adds that it requires a Pro plan and that return fields are fractions (e.g., 0.05 = +5%), complementing annotations without contradiction. No missing behavioral traits.

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?

Single paragraph is efficient and front-loaded with the main purpose. Could be slightly more structured (bullets for fields), but no redundancy. Every sentence adds value.

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 purpose, usage guidance, behavioral nuances, and parameter details. Does not mention error handling or rate limits, but given simplicity (single param, no output schema) and annotations, it is sufficiently complete.

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 covers the CIK parameter fully. Description adds value by noting leading zeros optional, providing a concrete example (Tim Cook), instructing to resolve names via search_insiders, and clarifying return format (fractions).

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 clearly states it aggregates a career rollup for one insider by CIK, listing specific data fields. It explicitly distinguishes from get_insider_transactions, making its purpose unambiguous and distinct among 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?

Explicit usage guidance: 'Use this instead of get_insider_transactions when you want a pre-computed summary rather than raw rows; pair with the generated get_insider_scorecard'. Provides when-to-use, when-not, and recommended companion tool.

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 declare readOnlyHint and openWorldHint, so the description carries the real behavioral burden and does so richly: the 5,000-insider cap, the 3-transaction threshold, daily rebuild with `refreshedAt`, the shared sitemap shard guaranteeing no drift, absence of plan gating, and the filer-group dedup rule with `filerGroupSize` explaining omitted actors. This is well beyond what the annotations provide.

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 return shape are front-loaded in the first two sentences, and each paragraph covers a distinct concern (ordering, dataset membership, filer-group dedup). The closing paragraph on filer groups is somewhat long and includes a supporting statistic, but it earns its place by explaining why rows are deduplicated.

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 and four parameters, the description fills the gap by describing the rail/counts payload, `refreshedAt`, and `filerGroupSize`, plus how the returned names are ordered and where the data comes from. An agent can call and interpret this tool correctly from the definition 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 description coverage is 100%, so the baseline is 3. The description restates the `letter` omission behavior and the `limit`/`per_page` alias rather than adding new parameter-level meaning (e.g., no guidance on page bounds interaction beyond what the schema already states). The extra 'casing is not normalised' note describes the returned data, not the parameters.

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 first sentence states a specific verb and resource (browse insiders alphabetically by surname) and immediately describes the return shape (A-Z rail with per-letter counts plus one page). It also names the alternative surface (GET /v1/insiders?name=), so the agent can distinguish this from the other insider-listing siblings 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?

It gives explicit routing conditions: omit `letter` for the rail and totals with no rows, and use GET /v1/insiders?name= to find someone outside the capped 5,000-insider set. It also states eligibility (3+ non-superseded transactions) and that the tool is not plan-gated, which is exactly the when/when-not information an agent needs.

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?

Discloses key behavioral traits beyond annotations: uses absolute return (not market-adjusted), only discretionary open-market buys, excludes non-10b5-1 buys, min_trades floor of 5, caching for 1 hour, and plan requirement. These details are not in the readOnlyHint or openWorldHint 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?

Well-structured with front-loaded purpose. Each sentence adds value, but the description is relatively long. For the complexity, it's acceptable; minor room for tightening.

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 return values implicitly, explains methodology, plan requirement, and caching. Without an output schema, it provides adequate context for an agent to understand what is returned and how it is computed.

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 adds value by explaining the min_trades floor (silently raised to 5) and referencing the scoring methodology. However, it does not enumerate each parameter's details beyond what the schema provides.

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 clearly states the tool returns a ranked leaderboard of insiders by buy track record, distinguishing it from the per-insider scorecard sibling tool. It uses specific language like 'ranked leaderboard' and 'scored-buy methodology' to convey purpose.

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 'Use this to discover which insiders have the best track record; use the per-insider scorecard once you have a specific CIK.' It also notes the Business plan requirement and caching behavior, guiding appropriate usage.

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 readOnlyHint and openWorldHint, but the description adds real context beyond them: what the tool deliberately does NOT return, that no transaction data is included, and a free-plan note. It stops short of describing pagination or failure modes for an unknown CIK, so it is not quite a 5.

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, each earning its place: identity-first, then the exclusion and sibling routing, then the CIK-resolution prerequisite and plan note. 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 takes on the burden of describing returns and does so concretely (name, titles, role flags, no transactions). Combined with the sibling routing and prerequisite, an agent has everything needed 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?

Schema description coverage is 100% for the single cik parameter, and the description largely restates the same CIK/leading-zeros/resolve-first guidance already in the schema. Baseline 3 applies when the schema does the heavy lifting.

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+resource ('Identity card for one insider by CIK') and enumerates the returned fields (name, titles, role flags). It explicitly distinguishes itself from get_insider_transactions and get_insider_career_summary, so an agent can tell them apart without opening any 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 explicit when-not ('Returns NO transactions') and routes to two named alternatives depending on intent (raw rows vs aggregated rollup). It also covers the prerequisite: resolve a name to a CIK via search/search_insiders first.

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 annotations (readOnlyHint, openWorldHint), description details scoring methodology (absolute return, anchored at filing close), hit definition, handling of small samples, no caching, and specific return value formats (fractions). No contradiction with 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?

Description is comprehensive but efficiently structured: opens with purpose, then methodology, usage guidance, edge cases, and format notes. Every sentence adds value without unnecessary repetition.

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 all essential aspects: required parameter, output fields (with fraction notation), sample sufficiency guard, error scenarios, plan restrictions, and computational behavior. Suitable for correct invocation despite lack of output 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?

Input schema fully describes the single parameter (cik) with 'exact match'. Description adds contextual value by mentioning plan requirement and 404 error for missing CIK, which aids agent understanding of parameter validation and error handling.

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?

Description clearly states it returns a scored track record of insider buys, differentiates from sibling tools like get_insider_summary (raw totals) and get_insider_leaderboard (ranking many insiders), and specifies the methodology and output fields.

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 describes when to use this tool (for scored track record) versus alternatives, notes plan requirement (Pro+), mentions error conditions (402, 404), and explains when fields are null due to sample insufficiency.

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 and openWorldHint. The description adds that the tool is paginated with a max of 100 per page and is on a free plan, providing useful behavioral context beyond 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?

Two sentences: the first states the purpose and filters, the second gives usage guidance. Every sentence adds value, no fluff.

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 8 parameters and no output schema, the description covers the key aspects: what the tool returns (Form 4 rows), pagination limits, and differentiation from similar tools. It is sufficiently complete for an agent to use 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 description coverage is 100%, so the schema already documents all parameters. The description briefly summarizes the filterable fields (ticker, transactionCode, date range, exclude_10b5) but does not add significant 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?

The description clearly states the tool retrieves all Form 4 transactions for a specific insider by CIK, and distinguishes it from siblings by noting that get_transactions provides broader filters and get_insider_career_summary returns aggregated data.

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 advises to use the tool after obtaining an insider's CIK and contrasts it with alternative tools, covering when to use each. Also mentions free plan and pagination limits.

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?

Describes the response structure (endpoint, status, duration, timestamp), auth requirement, and the ordering (most recent first). Annotations indicate readOnly, which aligns; the description adds valuable context beyond 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?

Three concise, front-loaded sentences: function, usage, auth. No wasted words, well structured for quick 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?

Given the simple interface (1 param, no output schema), the description is complete: covers purpose, return fields, use cases, auth, and alternatives. No gaps.

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% and fully describes the 'limit' parameter with defaults and maximum. The description does not add additional meaning beyond what the schema provides, so baseline score of 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?

The description clearly states the tool returns recent per-request API activity logs for the authenticated key, and distinguishes it from the sibling tool for aggregate usage trends by name.

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 provides when-to-use scenarios (debugging, checking errors, spotting slow requests) and when-not-to-use (usage trends), with a direct reference to the alternative tool.

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 indicate readOnly and openWorld. The description adds value by detailing pagination (max 100/page) and the Business plan requirement, which are behavioral traits not 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?

The description is three sentences, each serving a clear purpose: stating the function, explaining filters and pairing, and noting requirements and limits. No redundant 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 read-only browsing tool with good annotations and schema, the description covers essential usage aspects (filters, companion tool, plan requirement, pagination). No output schema exists, but the return value is implicitly clear.

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 baseline is 3. The description reiterates the partial match and minimum AUM filter, but does not add significant new meaning beyond what the schema already provides.

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 clearly states the tool browses the institutional manager index with specific data (latest 13F-HR filing date and AUM). It distinguishes itself from siblings by mentioning pairing with get_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?

The description provides context for use (browsing managers) and suggests pairing with get_holdings. It also notes the Business plan requirement. However, it does not explicitly exclude scenarios where other tools might be better.

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 and openWorldHint. The description adds valuable context: no API key required, cached for ~12 hours, and lists the specific fields returned. Does not contradict 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 description is front-loaded with purpose and key feature (no API key). It lists the returned fields but could be slightly more concise by grouping related items. Still, every sentence earns its place.

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 zero parameters, no output schema, and clear annotations, the description provides complete context: what it returns, use cases, limitations, caching, and alternatives. No gaps.

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?

No parameters exist, so baseline is 4. Description does not need to add parameter 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 clearly states it returns public corpus-wide statistics and distinguishes itself from sibling tools like get_company_overview and get_data_quality by specifying where to find per-company or per-insider data.

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?

Provides explicit guidance: use for corpus-wide totals (e.g., marketing widget), not for per-company or per-insider data, and suggests alternative endpoints. Also recommends get_data_quality for freshness metrics.

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 (readOnlyHint, openWorldHint) already indicate read-only and open-world behavior. Description adds specific behavioral info: new filings appear within ~60 seconds, returns specific fields like accession number, dates, identities, and transaction count. No contradiction with 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?

Two dense sentences with all key information front-loaded: purpose, sorting, filtering, timing, alternative tool, output summary, and constraints. No wasted words.

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, but description lists returned fields (accession number, dates, identities, transaction count) and mentions subsequent use of get_filing for full detail. Covers timing, filtering, pagination, and sibling comparison. Complete for a simple paginated read 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 covers all 3 parameters with descriptions, so baseline is 3. Description adds extra value by explaining the purpose of the ticker filter, noting pagination and max per_page limit, and describing output fields that imply what parameters control. Slight improvement over schema alone.

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?

Clearly states it's a live feed of newest SEC Form 4 filings, sorted most-recent-first, with optional ticker filter. Distinguishes from sibling get_transactions by specifying its use case for checking current activity rather than historical search.

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 tells when to use this tool ('what just happened') vs. get_transactions (filtered/historical). Also mentions free plan, pagination, and max 100 per page, giving clear operational context.

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 (readOnlyHint, openWorldHint) are minimal; the description adds critical behavior: automatic exclusion of 10b5-1 plan trades, explaining that the score reflects discretionary conviction. This is beyond 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?

Four concise sentences, front-loaded with the core purpose. Every sentence adds value: purpose, behavioral note, alternative usage, requirement. No redundancy.

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?

Despite no output schema, the description adequately explains the return value (one point per month, range -100 to +100). Combined with the schema and minimal annotations, the description is sufficient for a simple read-only 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 description coverage is 100%; both parameters have clear descriptions. The tool description adds only minor nuance (e.g., case-insensitive for ticker, default months), not significantly beyond what the schema provides.

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 clearly specifies the verb (get), resource (insider-sentiment score), and scope (by ticker, monthly, with range -100 to +100). It distinguishes from sibling tools like get_transactions and get_signals by noting they provide trade-level detail.

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 states when to use alternatives: 'Use get_transactions or get_signals for the trade-level detail behind a given month.' Also notes the Business plan requirement, setting usage prerequisites.

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 readOnlyHint/openWorldHint annotations, it discloses that 10b5-1 plan trades are excluded by construction (a non-obvious data-semantics fact), that a Business plan is required with a 402 upgrade_required response otherwise, and that results are paginated at max 50/page. These are exactly the behavioral facts annotations cannot 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?

Front-loads the concept definition, then routing, then constraints. No sentence is filler: even the return-field list earns its place because no output schema exists.

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 names the returned fields (signal type, detection date, buyer/seller counts, total value, underlying transactions) and covers auth, pagination, and result semantics. Nothing needed to call 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 description coverage is 100%, so page, per_page, ticker, cluster_buy, and cluster_sell are already fully documented, including the omit-both-to-get-either rule. The description adds pagination context but no parameter syntax or format detail beyond the schema, 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+resource and defines the domain concept ('multiple insiders at the same company trading in the same direction within a short window'), then distinguishes the tool from both explain_signal and get_transactions by name. An agent can identify this as the market-wide signal-discovery tool without opening any 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?

Explicit routing: 'Use this to FIND which companies have signals', call explain_signal when a company is already named and the user asks WHY, and use get_transactions for raw unaggregated search. Both alternatives and the selecting conditions are stated.

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?

The annotations already declare readOnlyHint=true and openWorldHint=true, and the description builds on them with substantial behavioral detail: the 5-minute heartbeat cadence, DB-connectivity nature, pro-rating of partial days, 5-minute caching, and no API key or plan requirement. It also explains the semantics of start date and overallPct, which is far beyond what annotations alone provide. There is no contradiction between description and 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 description is long but every sentence carries useful information: response shape, date window semantics, computation method, intended usage, alternative tool, caching, and auth requirements. It is front-loaded with the core purpose and avoids filler or redundant phrasing.

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 correctly carries the full burden of explaining the return value: the days array, per-day slot counts, uptime percentages, overallPct, and start date behavior. It also covers parameters, caching, and auth requirements. An agent has enough information to call the tool correctly and interpret its response without external 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?

The tool has zero parameters, so there is nothing meaningful to add beyond the empty input schema. The description explicitly states 'Takes no parameters,' which removes any assumption that a timeframe or entity filter might be required. Given the zero-parameter baseline, this is appropriately handled.

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 opens with a specific verb and resource: 'Measured uptime history for the public status page — trailing 90-day daily breakdown.' It clearly distinguishes what the tool returns from other data endpoints, and later explicitly contrasts it with live freshness data from GET /v1/data-quality. This is enough for an agent to understand the tool's distinct purpose.

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 is explicit about when to use the tool: 'Use this to render an uptime history / status bar; for live corpus freshness use GET /v1/data-quality instead.' It gives a positive use case, a negative use case, and names the alternative endpoint. No agent would need to infer usage context.

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 declare readOnlyHint and openWorldHint, so the description carries plan/auth behavior: which params are Free vs Pro, that Pro-gated params cause a 403 rejection rather than silent ignoring, and that paging depth is plan-limited with a 402 beyond the cap. It also states the row contents returned and the date-vs-filed-date distinction, adding context well beyond 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?

Front-loaded with verb+resource before the filter inventory, and every clause carries operational value (plan gating, alternatives, bulk path). It is dense and somewhat long, with pagination and the export fallback stated twice, so it is efficient rather than flawless.

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 33-parameter tool with no output schema, the description covers the return shape, plan requirements, pagination limits, error codes, and sibling routing. Nothing an agent needs to call 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 description coverage is 100%, so the baseline is 3. The description groups the filters and clarifies the fraction convention (0.05 = +5%), but this is already documented per-parameter in the schema, so it adds little meaning beyond the structured fields.

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) and resource (SEC Form 4 insider transactions), then enumerates the filter dimensions it supports. It explicitly names the siblings it is not (get_recent_filings, get_insider_transactions, get_company_insiders), so an agent can disambiguate without opening any 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 an explicit selection rule: use this for filtered/historical multi-company search, use get_recent_filings for an unfiltered live feed, and use the insider/company tools when an entity is already known. It also routes bulk pulls to the REST export endpoint, which is a concrete when-not-this-tool instruction.

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 and openWorldHint. The description adds specific context: requires valid X-Api-Key (401 otherwise), data is per calendar day UTC, and window is trailing. No contradictions.

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, no wasted words. Front-loaded with core purpose, then usage guidance. Every sentence serves a clear function.

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 simple single-parameter tool with no output schema, the description covers purpose, usage guidelines, auth requirement, and return format (daily time series). Could be slightly improved by explicitly stating the output structure (e.g., array of {date, count}).

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 the single parameter 'days' with its default and maximum. The description adds little extra beyond mentioning 'trailing N days' and 'one data point per calendar day'—the latter relates to output, not parameter semantics.

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 clearly states the tool returns 'daily request counts for the authenticated key over a trailing window' as a time series, and distinguishes itself from siblings by naming specific alternatives for different use cases (single snapshot or raw log).

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 when to use this tool ('plot usage trends or check rate-limit headroom over time') and when not to, referencing exact alternative endpoints. Also notes authentication requirement.

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 readOnlyHint/openWorldHint annotations: discloses the 500-row cap, most-recent-first ordering, the exact returned fields, the dead-delivery flag, the 30-day `since` limit, the 401 auth requirement, and plan-gated payload redaction. This is unusually rich operational context.

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 action, and nearly every sentence carries distinct information (limits, auth, redaction). It is dense and slightly repetitive in restating the 24h default, but not padded.

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 fully compensates by enumerating the returned fields and explaining payload nullability and plan gating. An agent has everything needed to call 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 coverage is 100% and the single `since` parameter is fully documented in the schema, so the description's restatement of the default and 30-day bound adds little. Baseline 3 is appropriate; the remaining bulk of the description describes response fields, not parameters.

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 (replay/retrieve) and resource (webhook delivery events) with an explicit default scope (last 24h). It is clearly distinguishable from list_webhooks, which enumerates subscriptions rather than delivery attempts.

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 names the scenario — reconciling missed deliveries after a receiving-endpoint outage — and contrasts it with relying on push delivery. However it does not name the sibling alternative or state when not to use it.

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 readOnlyHint=true and openWorldHint=true annotations, the description reveals key live behaviors: the result is uncached, the exact staleness thresholds for each component, the overall status values, and the HTTP 503/200 response semantics. That is strong behavioral transparency.

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?

Though the description is dense, every clause earns its place: thresholds, status logic, HTTP behavior, and authentication requirements are all covered without fluff. The leading 'Ingestion-death detector' immediately orientates the agent.

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 zero-parameter, no-output-schema health utility, the description provides all the context an agent needs to invoke it and interpret the result: what is measured, when it is considered stale, what overall statuses occur, and what HTTP status is returned. Nothing crucial 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?

The tool takes zero parameters and schema coverage is 100%, so there are no parameter semantics to document. The baseline for a parameterless tool is appropriate here, and the description correctly focuses on behavior instead of parameters.

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 precise resource ('Form 4 freshness, parse-queue health, price-feed freshness') and an actionable verb ('detector'/'Returns live ingestion health'). It clearly differentiates this tool from the broader sibling set focused on filings, insiders, or usage by centering on ingestion pipeline health.

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 gives explicit context on when to use the tool: it can be pointed at directly by an external uptime monitor, and it requires no API key or plan. It does not enumerate alternatives or say 'use X instead of Y', but the use case is clear enough.

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 indicate readOnly and openWorld. Description adds that it returns a single page, always top limit, sort order behavior (case-insensitive, fallback), and no page parameter. No contradictions.

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?

Single paragraph with logical flow: purpose, usage constraints, entry details, sort behavior. Efficient but could be slightly more concise.

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 purpose, use cases, entry fields, sort behavior, limits, plan access. No output schema but details what each entry includes, making it complete for agent understanding.

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% but description adds meaning: explains sort options (name/totalfilings), default, case-insensitivity, fallback; clarifies limit defaults and max; explains no page parameter.

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?

Description clearly states the tool lists companies with public tickers, sorted by name or total filings, for browsing or building a company picker. It distinguishes from sibling tool by directing to use GET /v1/companies/{ticker} for exact ticker search.

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 states when to use (browsing/picker) and when not (searching by name/CIK), provides alternative endpoint, explains no page parameter and default sort behavior. 'Not plan-gated' adds clarity.

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 readOnlyHint/openWorldHint annotations: sells include both Sale and PartialSale, Exchange trades count only toward total, ordering is total-count desc with recency tie-break, and it discloses the Pro-plan requirement plus the resulting 402 PLAN_REQUIRED for Free/Starter. The 'Query runs live — no caching' note is exactly the kind of runtime trait 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 the resource and the routing guidance, and most sentences carry distinct facts (counts semantics, ordering, plan gate). It is somewhat dense and the alias note slightly restates the schema, but nothing is gratuitous enough to call 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?

With no output schema, the description compensates by enumerating the returned fields (total/buy/sell counts, most recent disclosure date), the ordering guarantee, and the filtering precondition. An agent has everything needed to call it correctly 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 coverage is 100% and the description's only parameter claim ('limit is accepted as an alias for per_page') is already stated verbatim in the schema. It adds no syntax, format, or default information beyond what the structured schema provides, so the baseline of 3 is appropriate.

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+resource ('Ranked rollup of politicians by congressional trade activity') and immediately scopes it as a paginated list of politicians with at least one non-superseded trade. It distinguishes itself from list_congress_trades and get_congress_politician by describing the rollup nature and naming the profile endpoint as the alternative.

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 discover active traders; for one politician's full profile (including their most-traded tickers and recent trades) use GET /v1/congress/politicians/{idOrSlug}' gives an explicit when-to-use and a named alternative with its selection condition. Plan gating is also flagged, so the agent knows the eligibility prerequisite.

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 declare readOnlyHint and openWorldHint, but the description adds substantial behavioral context: House-only coverage with the Senate 403 reason, plan-clamped disclosure window floors per plan, non-superseded row semantics, live non-cached queries, and date-quality flagging rules. This is far beyond what the annotations convey.

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 scope before diving into coverage, plan-clamping, and date quality, with clear ALL-CAPS section headers aiding scanning. It is longer than strictly necessary and lightly repetitive in restating filter behavior, but every section carries information an agent needs.

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 listing tool with no output schema and no required fields, the description covers the return shape (paginated JSON, most-recently-disclosed-first, non-superseded rows), coverage limitations, plan gating, and data-quality semantics. Nothing critical for 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 description coverage is 100%, so the schema already documents every parameter, including the chamber coverage caveat and the plan-clamped floor for disclosure_date_from. The description largely restates those same filter semantics rather than adding new meaning, so it sits at the baseline for fully documented schemas.

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?

Opening sentence states a specific verb (Query) and resource (congressional STOCK Act trades), with scope qualifiers (Free+, plan-clamped window). It is clearly distinguishable from sibling tools like list_congress_politicians and get_congress_ticker_rollup, which are named and routed away from.

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 names alternatives and their conditions: per-politician/per-ticker rollups go to the /v1/congress/* endpoints (Pro+), cluster alignment to /v1/signals/convergence, company profile to /v1/companies/{ticker}. It also tells the agent when chamber=Senate is a dead filter and to read X-Coverage-Note rather than treat empty as 'no trades'.

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/openWorld annotations, it discloses pagination, newest-filed-first ordering, the null semantics of acceptedAt, the alias behavior of limit, and the access state ('Not plan-gated'). These are exactly the behavioral traits an agent cannot get from the schema or 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, then return shape, then routing guidance; each sentence carries weight. Slightly long because the filter list is effectively restated from the schema, but there is no 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 fully enumerates the returned fields (accession number, ticker/name, period, filed date, acceptedAt, documentUrl, amendment type, transaction count) and notes pagination and ordering, so an agent knows both how to call it and what it gets back.

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 seven params are already documented in the schema (including the limit/per_page alias and the 'per_page wins' rule). The description restates the ticker/cik/from-to filters but adds no syntax or format detail beyond what the schema provides, 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 (List) and resource (Form 4 filings) with its filter dimensions, and explicitly distinguishes itself from sibling tools get_recent_filings and get_transactions by naming the alternative endpoints. An agent can identify the tool's role without opening any 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 states 'Use this for a company's filing HISTORY', names the two alternative tools (recent live feed with no page param; transactions for individual trades) and the conditions that select each. 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.

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

Goes well beyond the annotations: it discloses that superseded SC 13D/A and 13G/A rows are excluded, that isAmendment describes the row itself rather than supersession, that the query runs live with no caching, and that Free/Starter/Pro get a 402 PLAN_REQUIRED error. These are exactly the operational traits an agent needs that the readOnly/openWorld hints do not 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?

Front-loaded correctly with the tool's scope in sentence one, but the middle is padded with regulatory lore (2023 rule compliance dates, 10-to-5-day deadline history, 2024-09-30 effective dates) that does not help selection or invocation. The load-bearing facts (superseded-row exclusion, isAmendment semantics, plan gate) have to be dug out of a dense block.

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 joint-filing multi-row behavior. Combined with the plan requirement, live-query note, and alias handling, an agent has everything needed to call it correctly for a read-only listing 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 schema already documents every parameter including the limit/per_page alias and the 13D/13G meanings. The description largely restates that schema text (e.g. the limit alias) rather than adding new semantics, so the baseline of 3 holds.

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 opens with a specific verb+resource+scope ('List Schedule 13D/13G >5% beneficial-ownership crossings (Business plan+)') and enumerates the returned fields (filer, ownership percent, event date, form type, amendment status). The resource is narrow enough to separate it from generic siblings like list_filings or get_form144, though no sibling is explicitly named for contrast.

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 implied rather than stated: the description explains what 13D vs 13G mean and that results exclude superseded rows, letting an agent infer when this beats a generic filings list. It never says when to prefer this over list_filings/get_filing, nor any when-not condition beyond the plan gate.

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 declare readOnlyHint/openWorldHint, and the description adds substantial context beyond that: which rows are permanently excluded, that the signing secret is never returned (shown once at creation), and that a valid X-Api-Key is required (401 otherwise). This is exactly the kind of behavioral disclosure annotations can't 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?

The purpose is front-loaded and every sentence conveys real information, but the text is dense for a zero-param list tool and repeats 'disabledReason' multiple times, making it slightly longer than necessary.

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 fully by enumerating the returned entry fields (id, target URL, event types, creation date, active flag, disabledAt/disabledReason, isReadOnly) and the exclusions. An agent has everything needed to interpret results and know the auth requirement.

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?

There are zero input parameters, so the baseline is 4 and there is no parameter syntax to add. The description instead documents the returned fields, which is useful but belongs to output/behavioral rather than parameter semantics.

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 opens with a specific verb+resource: 'List webhook subscriptions owned by the authenticated API key.' This clearly distinguishes it from siblings like get_webhook_events or the many financial-data tools, so an agent can identify the tool's role 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?

It explains the exact scope of what is and isn't returned (active, auto-disabled, user-deleted, legacy rows) and even points to the remediation path (POST /v1/webhooks/{id}/enable). It doesn't name a sibling alternative, but for a zero-param listing tool there is no obvious competing tool, so guidance is effectively complete.

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?

Discloses graceful degradation with null and _unavailable notes, concurrency (fetches all sections concurrently), and plan-based availability (Free vs Business), which go beyond the readOnlyHint and openWorldHint 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 description is moderately sized but front-loaded with the main purpose, and each sentence adds value; however, it includes a disclaimer that could be separate, preventing a perfect score.

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 tool with no output schema, the description thoroughly explains the bundled components, plan behavior, concurrency, and degradation, providing sufficient context for an agent.

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. Description does not add significant new information about parameter meaning beyond the schema, though it contextualizes recent_limit within the bundled result.

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 clearly states the tool bundles company profile, insider transactions, signals, sentiment, and direction summary into one call, and explicitly distinguishes it from four sibling tools it replaces.

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 advises to use this tool FIRST for any insider-research question, replaces separate calls, and explains graceful degradation and plan requirements for when to use alternatives.

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 declare readOnlyHint/openWorldHint, so safety is covered; the description adds substantial context beyond them: two independently-ranked lists, exact ranking algorithms, whitespace-token matching semantics, null ticker possibility, the 2-64 char constraint with specific 400 error codes, limit behavior, and 'Free plan, no caching'.

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 front-loaded: the core purpose and primary use case come first, then return shape, then constraints. Every sentence carries information (ranking, matching, limits, errors), though the length is near the upper bound for a search 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?

With no output schema, the description fully covers the return value (two independently-ranked lists with their ranking criteria) and the input constraints, error codes, and scope. Nothing an agent needs to invoke and interpret 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 the baseline is 3. The description compensates further by explaining the matching semantics ('splitting the query on whitespace so every token must match') and that limit applies independently to each list, adding meaning beyond the schema's literal text.

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+resource (resolve free-text input to a ticker or CIK) and explicitly identifies itself as 'usually the right FIRST call' when no identifier is known. It clearly differentiates from siblings by naming the downstream tools it routes into (get_company_overview, get_transactions, get_insider_profile, get_insider_transactions).

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 states when to use it (user names a company or insider with no known identifier) and what to do with the output. The 'FIRST call' framing plus downstream routing gives the agent a clear decision rule rather than leaving it 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?

Beyond readOnlyHint/openWorldHint it discloses pagination behavior, the alphabetical fallback when no filter is supplied, the alias precedence rule, the QUERY_TOO_SHORT failure mode, and that the tool is not plan-gated. That is substantial operational context 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?

Front-loaded with purpose and return contents, then routing guidance, then edge cases in descending priority — zero filler. It is dense at three sentences, but every clause carries information (fields, CIK handoff, omission behavior, alias, tier).

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 still enumerates the returned fields and pagination, and it covers the error path, the no-filter fallback, and plan availability. An agent has everything needed to call it correctly and interpret the response.

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 `name` matching semantics, the 2-character minimum with its 400 error, `page`/`per_page` defaults and maximum, and the `limit` alias. The description restates the alias and omission behavior but adds no syntax or format detail beyond the schema, 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?

Specific verb+resource ('Search insiders') with the entity qualifier spelled out (officers, directors, 10% owners) and the return shape enumerated (CIK, title, flags, filing count). It is clearly separable from siblings like get_insider_directory and get_insider_profile, which return a person given an identifier rather than resolving a name to one.

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 states the when-to-use: 'resolve a person's name to their CIK before fetching their transaction history, career summary, or scorecard,' naming the downstream endpoints the CIK feeds. It also documents the degenerate case — omitting `name` returns alphabetical listing rather than searching — so the agent knows not to call it as a plain lister.

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 and openWorldHint. The description adds that the tool returns 'pass/fail/warn per check plus concrete next steps' instead of raw errors, and that it can isolate configuration vs. plan vs. backend issues.

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: first states purpose and return format, second tells when to use, third reassures no parameters. No wasted words, front-loaded.

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 zero-parameter, read-only diagnostic tool with no output schema, the description fully explains the return type (pass/fail/warn + next steps) and usage context. Nothing 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?

No parameters in schema, and description confirms 'No API key or parameters required'. This adds clarity that nothing is needed, scoring baseline 4 for zero-param tool.

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?

Clearly states it performs a diagnostic check for API key validity, backend reachability, and plan status. It distinguishes itself from siblings like check_usage or get_public_stats by focusing on setup verification.

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 tells when to use: 'Run this first whenever another tool fails or returns a 401/402'. Also notes that no API key or parameters are required, guiding the agent to use it as a first step.

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