arkolith

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

Annotations already state readOnlyHint=true. The description adds valuable context: it is free (0 credits), returns specific data (balance, USD, top-up URL), and emphasizes that checking balance never costs credits. 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?

The description is brief (two sentences) and front-loaded with the key fact (FREE (0 credits)). Every sentence is essential and no waste.

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 tool with no output schema, the description provides sufficient information about purpose and return content. Mentioning the three return items gives agents enough context, though a more structured format would improve precision.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0 parameters and 100% schema coverage, the baseline is 4. The description adds value by specifying what the tool returns, which aids understanding. No parameter details are needed.

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 the API key's credit balance, USD value, and top-up URL. It uses specific verbs like 'Return' and specifies the resource. It distinguishes from sibling tools by focusing on account balance monitoring, which is unique among the listed tools.

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 advises calling this tool for self-monitoring before/after spending, providing clear context. It does not mention alternatives, but none are directly relevant among siblings. The guidance is clear and actionable.

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=true, and the description confirms a read operation. Beyond annotations, it details output components (outcome, coverage, manager changes, insider activity, etc.) and clarifies edge cases like withheld direction and 13F reporting nuances. No contradiction exists.

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 the main purpose, then usage, output details, and special cases. It is front-loaded but somewhat verbose with minor repetition (e.g., 'Current-only' phrasing). Still, 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?

For a simple one-parameter tool with no output schema and read-only annotations, the description thoroughly covers purpose, usage, behavioral details, output structure, limitations, and interpretation of results. It is fully adequate for correct invocation and 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?

The single parameter 'ticker' is fully described in the schema (100% coverage) with an example and coverage note. The main description adds no additional semantic detail about the parameter itself, making the value-add minimal given the schema already handles it.

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 composes a capital-change brief for one ticker, specifying it covers institutional ownership changes, manager tracking, and Form 4 activity. It distinguishes from siblings like capital_rotation or fund.holdings by focusing on evidence-backed briefs and explicitly notes limitations (current-only, no as_of/since).

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 states when to use the tool: 'Use when a user asks what changed in reported institutional ownership...' and adds exclusions ('Current-only: pass ticker only; as_of and since are not supported'). It lacks explicit mention of alternative tools but provides clear context for appropriate use.

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 discloses key behavioral traits beyond the annotations: it is price-free, point-in-time, backward-looking (13F lag ~45 days), and every number is traced to 13F. It also explicitly states it is NOT investment advice. There is no contradiction with the readOnlyHint annotation; the description reinforces the read-only nature.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the most important information and is well-structured into purpose, mechanism, parameter usage, and disclaimers. Every sentence adds value, but it is slightly verbose (e.g., the phrase 'what the sell-side ships as a static quarterly PDF' is colorful but not strictly necessary). Still, it is efficient for the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 4 parameters, no output schema, and moderate complexity, the description is highly complete. It explains the output format (sectors with breadth, net flow %, rotation rank), the data source (13F), and limitations (backward-looking). It also covers default behaviors (latest quarter, direction both, limit 12). No important gaps are apparent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the description adds significant meaning beyond the schema. For example, it explains the 'weight_by' options (fund_quality vs equal) with context about what fund_quality incorporates. It also clarifies the 'direction' enum with plain language ('into', 'out_of', 'both'). The description provides practical usage context that helps the agent select appropriate 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 clearly identifies the tool as THE flagship 'where is smart money rotating' signal, specifying that it aggregates 13F position changes into per-sector capital flows. It distinguishes itself by being price-free, point-in-time, and traced to 13F data, and gives concrete examples of questions it answers ('is smart money rotating out of tech into energy/utilities?'). This provides a specific verb+resource and differentiates it from sibling tools.

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 includes guidance on when to use the tool (to track smart money rotation across sectors) and provides parameter usage instructions (e.g., 'Pass `period` for a specific quarter, else the latest well-covered one'). It also includes a disclaimer about backward-looking nature and that it is not investment advice. However, it does not explicitly state when NOT to use it or compare directly with sibling tools, which would improve the score to 5.

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

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

Annotations provide readOnlyHint=true, but the description adds critical behavioral context: estimated dates are sponsor-self-reported and slip often, making it a readout window rather than a hard date. This goes well beyond the annotation alone.

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 plus a short caveat paragraph. Purpose is front-loaded, filters and sorting are clearly listed, and key warnings are isolated. No extraneous 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?

Despite no output schema, the description enumerates all returned fields. Given the complexity (7 optional parameters, no required fields), the description fully covers inputs, usage, and output shape.

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 adds meaning by explaining that 'nct_id' bypasses standard search, clarifies default values for limit, phase, status, and within_days, and explains the nature of the date window.

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?

Starts with 'Upcoming clinical-trial readout catalysts' which is a specific verb+resource. Clearly states it searches for clinical trials with upcoming readout dates, filterable by sponsor, condition, phase, and date window. Distinct from sibling tools which are largely financial or political.

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 lists filters and sorting ('sorted soonest-first'), and provides a caveat that estimated dates are unreliable and that press releases beat this feed. While it doesn't name specific alternatives, no sibling performs a similar function, so this is clear 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?

Matches readOnlyHint annotation. Adds critical context that the tool returns an index, not parsed trades, and explains each filingType value. 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?

Front-loaded with purpose, then details. Three concise sentences with no wasted words. Slightly verbose in second sentence but overall 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?

No output schema, but description fully explains return format (one row per filing with PDF link) and limitations. Also explains filingType enum values. Complete for a list 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 description adds minimal value beyond schema. FilingType examples are helpful but already in schema descriptions. Baseline 3.

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 lists the US House financial-disclosure filing index for a year, linking to source PDFs. It distinguishes from sibling tool congress.trades which provides parsed 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?

Explicitly states when to use this tool (for the index, not parsed trades) and directs to congress.trades for parsed line-items. Also mentions filingType values and limitations (Senate being added).

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 confirm read-only; description adds current scope (US House live) and future plans (Senate being added), enhancing transparency beyond annotations. 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 sentence packs all key information: verb, resource, criteria, and cross-reference to sibling tool. No superfluous words, front-loaded with purpose.

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 two-parameter search tool with no output schema, description adequately covers purpose, scope, and relationship to siblings. Minor gap: no mention of pagination or results format, but acceptable given simplicity.

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 adds value by clarifying 'name' accepts partial matches and year defaults to 2024. Also connects to 'filing index' concept, aiding understanding.

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 finds US House representatives by name and year, distinguishing it from siblings like congress.trades for parsed trades. Specific verb 'Find' and resource 'US House representatives' with clear scope.

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?

Mentions filing index and directs to congress.trades for parsed trades, providing context on alternatives. Could more explicitly state when not to use, but sufficient 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?

The description discloses that each row links to its source PTR PDF, covers both House (live) and Senate (being added), and details the data fields. Annotations already indicate readOnlyHint=true, and the description aligns with no contradictions, adding valuable context about data provenance and coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a concise two sentences. The first sentence packs the core purpose and data fields, while the second adds context on availability and usage. Every word earns its place; 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?

For a tool with no output schema, the description adequately describes the returned fields (buy/sell, amount range, dates, owner, PDF link) and coverage status. The agent can form a clear expectation of the tool's output without additional 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 parameters are already documented. The description adds value by reinforcing the mutual exclusivity of ticker and member, and providing concrete examples ('Pelosi', 'NVDA'), which aids the agent in constructing correct queries.

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 parses STOCK Act transaction line-items for actual congressional stock trades by ticker or member, with specific fields (buy/sell, amount range, dates, owner, PDF link). It distinguishes from siblings like congress.disclosures.list and congress.member.search by focusing on raw trade 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?

The description specifies to pass `ticker` OR `member`, implying mutual exclusivity, and notes that US House data is live with Senate being added. It provides clear context for when to use this tool (to get trade transactions), but does not explicitly exclude alternatives or provide when-not-to-use scenarios.

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 confirm readOnlyHint=true, so transparency burden is lower. The description adds important behavioral details: conditionality of copy-return fields on price-source policy and freshness gate, and the public-domain data source. 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?

The description is three sentences, front-loaded with purpose. Every sentence adds distinct value: purpose, sort options, data source. No redundancy or 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?

Without an output schema, the description adequately explains what each row contains (name, manager, AUM, etc.) and mentions the conditional availability of return fields. It covers the data source and key functionality. Minor omission: does not explicitly state that output is a list/array, but this is inferable.

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 descriptions for all parameters. The description restates sort meanings in plain language and mentions default limit, adding marginal value over the schema. It does not introduce new parameter details beyond what's in 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 ranks institutional managers (13F funds) worth copying, with a specific verb ('rank'), resource ('leaderboard of institutional managers'), and context ('who should I copy?'). It distinguishes from sibling tools like copy.target.get and fund.list by positioning itself as the entry point for identifying managers to follow.

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 explains how to use the tool: sort options (aum, active, followers, return) with clear definitions, and a default limit. It mentions that return fields are conditional on policy gates, guiding appropriate use. However, it does not explicitly state when not to use this tool or provide direct alternatives, leaving some ambiguity.

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=true, so the agent already knows it's safe. The description adds transparency by stating the data source (public-domain SEC EDGAR 13F data) and describing the output structure, including the quarter-over-quarter change categories.

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 long, no fluff. The first sentence efficiently conveys the primary purpose and output. The second adds context. 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?

Despite no output schema, the description fully explains the returned data (holdings with percentages and changes, book size, quarter, filing history). This is sufficient for the agent to understand what to expect.

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 adds no new information about the slug parameter beyond what is already in the schema. The description mentions 'from copy.leaderboard', which is also in the schema 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?

The description clearly states the action ('Get'), resource ('copy target (13F fund)'), and the key data fields returned (holdings with changes, book size, quarter, filing history). It distinguishes from sibling tools like copy.leaderboard by specifying retrieval of a single item by slug.

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 on usage: getting the slug from copy.leaderboard and pairing with watchlist tools. However, it does not explicitly state when not to use this tool or list 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?

The description explains that the tool performs cross-market comparison and warns about keyword correlation. Annotations already declare readOnlyHint=true, so the description adds context about the nature of the scan and the caveat, but does not detail other behavioral aspects like rate limits or authentication. This is adequate but not exceptional.

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: the first succinctly states the core function, and the second provides a critical usage warning. No extraneous information, perfectly front-loaded and 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?

For a scan tool without an output schema, the description conveys the key purpose and a crucial caveat. It does not describe the output format, but given the straightforward nature of comparing probabilities, it is mostly complete. A slightly more detailed output hint would be beneficial, but it is sufficient for an agent to understand what to expect.

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 describes both parameters (limit as max per platform, query as topic keyword) with 100% coverage. The description does not add substantial new meaning beyond the schema, so the baseline score 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?

The description clearly states it finds contracts from Polymarket and Kalshi for a keyword and compares implied probabilities to surface mispricing/arb. The verb 'scan divergence' is specific and the resource is cross-market contracts, distinguishing it from siblings like predictionmarket.list and predictionmarket.quote.

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 specifies that it's for a topic keyword and includes a warning that matches are keyword-correlated, not verified same-event, advising users to confirm before trading. This provides clear context for when to use (given a keyword) and a cautionary note, though it does not explicitly exclude scenarios like exact event matching.

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 discloses behavioral traits beyond the readOnlyHint annotation: the monotonic cursor behavior, that unsupported forms return an explicit note (never silent empty page), and the polling mechanics. 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?

Three sentences packed with information: purpose, usage pattern, parameter behavior, and edge-case handling. No filler, extremely 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?

The description covers the polling loop, cursor usage, and error handling for unsupported forms. It lacks explicit mention of rate limits or error responses, but for a watch loop tool the core mechanics are well explained. Given no output schema, it compensates well.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 100% schema coverage, the description adds significant meaning: explains the 'since' parameter as a monotonic cursor, mentions 'next_cursor' in response, and clarifies that unsupported form types return a specific note. This goes well beyond the schema definitions.

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 is a live SEC filing-event stream for Form 4 (insider) filings, with specific verbs like 'poll' and 'get'. It distinguishes itself by mentioning the roadmap and polling loop, differentiating from historical or search-oriented siblings like '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?

The description explicitly recommends using this tool in a watch loop ('Built for a watch loop, so call it on a schedule to never miss a filing') and explains how to use the 'since' cursor. It does not explicitly list alternatives or when not to use, but the context is very 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?

Discloses all relevant behavioral traits: read-only (consistent with readOnlyHint), return of historical actions, limitations on private sponsors, and data source. 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?

Somewhat lengthy but well-structured. Each sentence adds information: purpose, action types, flags, caveats. Front-loads the core function. Could trim slightly but overall efficient for the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 8 parameters, no required, no output schema, the description covers the essential context: what the tool does, what the results contain, and important limitations. Adequate for effective standalone use.

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 adds value by interpreting action meanings (AP bullish, CR bearish) and explaining flags. Does not repeat parameter descriptions but enriches understanding.

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 returns FDA drug approval and rejection actions from Drugs@FDA, CDER. Specifies action types (AP, CR, TA) and flags (NME, priority review). Distinguishes from siblings like fda.recalls by focusing on regulatory actions.

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 caveats: backward-looking, lags behind press releases, CDER-only (no biologics). Indicates it is a confirmation/archive feed, not real-time. Provides clear context for when to use versus 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 indicate readOnlyHint=true, and the description adds critical behavioral context: data freshness (weekly updates), immutability of classification status, and that the ticker field resolves to null for private firms. 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?

The description is a single, well-structured paragraph: purpose first, then class explanation, output fields, caveats, and data source. Every sentence adds necessary information without 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 read-only recall query tool with no output schema, the description adequately covers inputs, outputs, and data limitations. It explains classification meaning, output fields, staleness caveat, and the public-domain nature, making it complete for most use cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the meaning of classification values (Class I = death/serious harm) and that the 'recently' filter is based on report date. This helps the agent choose appropriate 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 clearly states it retrieves FDA drug recalls from the Recall Enterprise System, explains the class hierarchy (I vs II/III), and lists output fields. This distinguishes it from sibling tools like fda.approvals which cover approvals, not recalls.

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 explicit caveats: data updates weekly, recall status is never revised after classification, and it is not suitable for real-time alerting. This tells the agent when not to use it, though it does not explicitly compare to other FDA 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?

Description discloses that the tool is free, verifies an OK delivery receipt, records at most one verdict per organization and brief, and duplicate submissions return already_recorded=true. These behavioral traits complement the readOnlyHint=false annotation.

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 concise (~4 sentences) and front-loaded with key information. Every sentence serves a purpose without 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?

With 7 parameters (1 required) and no output schema, the description covers usage constraints, behavioral details, and parameter context comprehensively, leaving no ambiguity for an AI 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?

Although schema description coverage is 100%, the description adds context for parameters like workflow, brief_id, ticker, and verdict, explaining when they are required and the constraint on verdict. This provides meaningful guidance 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 is for submitting feedback to Arkolith, including data requests, bug reports, or ideas. It also specifies its role in the capital_change_brief workflow, distinguishing it from other tools.

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 the tool (after user explicitly says delivered answer useful or what was missing) and when not to (never infer usefulness from technical success). Provides specific instructions for capital_change_brief and notes duplicate behavior.

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 the description adds value by detailing what data is returned (top positions, CUSIP, QoQ change) and noting it is public-domain SEC EDGAR data. No contradictory information.

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, front-loaded with the primary purpose followed by details. Every word serves a purpose, with no unnecessary 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 simple tool with one required parameter and no output schema, the description adequately covers purpose, data source, and returned fields. Could mention potential limits or structure, but it's mostly 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?

The only parameter, cik, is fully described in the schema with 'SEC Central Index Key (zero-padded)'. The tool description does not add additional meaning beyond the schema, so 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?

The description clearly states the tool retrieves the latest 13F equity holdings for a fund by CIK, specifying 'top positions by value, each with its CUSIP and quarter-over-quarter change'. It differentiates from siblings like fund.holdings.as_of and fund.holdings.diff through the word 'latest'.

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 implies usage for getting the latest holdings snapshot but does not explicitly state when to use alternatives or provide exclusions. Sibling tool names offer some context, but the description itself lacks direct 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?

The readOnlyHint annotation confirms read-only access. The description adds significant behavioral context: 'the most recent filing whose filedAt <= as_of' explains how results are determined. 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?

Two concise sentences, front-loaded with the key concept 'Point-in-time holdings.' Every word adds value; 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?

For a simple tool with two required parameters, readOnlyHint, and no output schema, the description is complete. It explains what the tool does, how it works, and its intended use case (backtesting).

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 clear descriptions for both parameters (cik, as_of). The description adds overall context (point-in-time, no look-ahead) but does not provide additional parameter-specific details beyond the schema. 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?

The description clearly specifies the tool returns point-in-time holdings as known on a given date, with no look-ahead. It distinguishes from sibling tools (e.g., fund.holdings, fund.holdings.diff) by emphasizing historical accuracy and backtesting use.

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 states 'Built for backtesting,' providing clear context for appropriate use. It implies use for historical analysis but does not explicitly exclude other scenarios or name alternatives. Still, the guidance is strong.

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=true, and the description adds behavioral context by listing the types of changes returned (new positions, adds, reduces, exits). This transparency helps the agent understand the output without needing an output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the core concept. Every word adds value, with no repetition or 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?

For a simple tool with one parameter and no output schema, the description fully covers the tool's function and return behavior. No gaps in context given the complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'cik' is fully described in the schema as 'SEC Central Index Key'. The description does not add extra semantic detail beyond the schema, which is acceptable given 100% schema coverage. Baseline score 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?

The description clearly defines the tool's purpose: it provides quarter-over-quarter changes (new, adds, reduces, exits) for a fund's most recent 13F filing. The verb 'diff' is well explained, distinguishing it from siblings like 'fund.holdings' or 'fund.holdings.as_of'.

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 context is implied by the description (e.g., 'to see changes over quarters') but no explicit guidance on when to use this vs. alternatives (e.g., fund.holdings). Sibling names exist but are not referenced in the description.

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=true; description adds behavioral context (returns ranked list, specific fields, data source). No destructive behavior suggested; no contradiction.

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: action, return fields with usage hint, and data source. Front-loaded, no filler, 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?

Sufficient for a simple list tool with one optional parameter. Explains output and integration with other tools, no missing critical info.

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 has one parameter (limit) with complete description. The tool description does not add further parameter semantics, so 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?

Explicitly states the tool lists institutional managers filing SEC 13F, ranked by AUM, and specifies return fields (name, AUM, quarter, holdings, CIK). Clearly distinguishes from sibling tools like fund.holdings by explaining CIK usage.

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?

Tells agent to 'start here' to find funds to track and explains how CIK links to other fund tools. Does not explicitly list when not to use, but the context is clear for a listing 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 declare readOnlyHint=true, so the tool is safe and non-destructive. The description adds value by specifying the output includes quarterly shares and USD values, and that the time-series spans across filings. This exceeds the annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the key purpose. Every phrase adds value: 'time-series', 'single security', 'by ticker or CUSIP', 'across fund filings', 'shares and USD value per quarter'. 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?

Given the complexity and lack of output schema, the description adequately indicates the output format (shares and USD per quarter). It could benefit from mentioning what happens if no filings exist or if the security is not found, but overall it provides sufficient context for an agent to decide to use this 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% with all parameters described. The description adds minimal extra meaning beyond the schema, just noting that ticker and CUSIP are alternatives and that cik is the fund identifier. 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?

The description clearly states it provides a time-series of a single security position across a fund's filings, specifying shares and USD value per quarter. It distinguishes from sibling tools like fund.holdings by emphasizing historical sequence over snapshot.

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 does not provide explicit guidance on when to use this tool versus alternatives such as fund.holdings or fund.holdings.as_of. The usage is implied by the focus on time-series, but no direct comparison or exclusion criteria are given.

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 annotation, the description details that the score is not realized performance, that ties share a rank, and how sparse data is shrunken. This adds valuable behavioral 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?

The description is moderately lengthy but front-loaded with the core purpose. Each sentence contributes meaningful information, though minor redundancy could be trimmed.

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 what the tool returns (sorted leaderboard), eligibility, ranking factors, exclusions, and data caveats. It is complete for a complex 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% with descriptions for all three parameters. The description adds context about sort fields and period interpretation, but does not significantly enhance the parameter understanding 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 it ranks institutional funds by a specific focus score, explaining the three weighted components. It distinguishes from sibling tools by specifying it's about 13F book focus, not transactions or 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 explains that it ranks eligible institutional funds and notes taxonomically excluded fund types. It does not explicitly provide when-not-to-use scenarios, but the context of 'PRICE-FREE; NOT investment advice' sets clear expectations.

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

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

The description details what the tool returns (verdict, sector context) and labels it 'PRICE-FREE; NOT investment advice'. Annotations indicate readOnlyHint=true, and the description does not contradict that. Behavioral traits are fully disclosed.

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, front-loaded with the tool's core action, and contains no extraneous words. Every sentence serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (multiple data sources, verdict, sector rotation), the description completely covers its purpose, inputs, and outputs. No additional documentation is needed for an agent to understand what this tool does.

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%; the description adds context that 'days' is for lookback for corroboration. It does not repeat parameter details verbatim but supplements with usage context, adding value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns a cross-source confluence verdict for one ticker, plus capital-rotation context. It distinguishes from siblings like 'divergence.scan' by focusing on agreement across specific sources (institutions, insiders, Congress) and adds sector rotation context.

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 says 'For ONE ticker' and notes Congress is a 'free corroborating leg (never the sole basis)'. This implies appropriate use for single-ticker consensus checks. It does not explicitly mention when not to use or specify alternatives, but the sibling list provides 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 already declare readOnlyHint=true. Description adds value by explaining the ranking criteria (distinct-insider count and total value) and that it returns tickers. No contradictions noted.

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, zero wasted words, front-loaded with the main purpose. Very efficient and well-structured.

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 read-only scan tool with no output schema, the description fully covers functionality and output (ranked tickers). No missing information.

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 does not add additional meaning beyond what the schema provides for parameters like days, side, limit, min_insiders.

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 uses specific verb 'scan' and resource 'insider clusters', clearly stating it scans market-wide for companies with multiple distinct insiders buying or selling. This distinguishes it from siblings like insider.company or 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?

Description implies usage for broad market screening of high-conviction cluster signals. While it doesn't explicitly state when not to use, it provides sufficient context (market-wide vs. individual company) to differentiate from siblings.

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. The description adds context about the output (buy vs sell value, shares, counts) and the window limitation (days, max 365), going beyond annotations without contradiction.

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 specifies the tool's output, the second states the question it answers. No wasted words, front-loaded with key intent.

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 read tool with two well-described parameters and no output schema, the description sufficiently explains purpose and output format. It does not detail return structure but is adequate for agent invocation.

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 descriptions for days and ticker. The description adds meaning by linking parameters to the question and noting 'open-market' activity, enriching the schema baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Net insider activity for one company over a window: open-market buy vs sell value/shares and distinct buyer/seller counts' with a clear verb and resource, and distinguishes from sibling tools like insider.clusters or insider.filing by focusing on net flow.

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 a clear use case: 'Answers are insiders net buying or selling this name right now?' It implies timing but does not explicitly say when not to use it or mention alternatives, though sibling tool names are available in 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 already declare readOnlyHint=true. The description adds value by specifying the output contents (insider, issuer, transactions, net flow, link), enhancing transparency beyond the annotation alone.

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 with no filler. The first sentence packs essential purpose and output, the second gives usage context. Every word 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?

Despite lacking an output schema, the description thoroughly explains what the tool returns. It covers purpose, input, and usage context completely for a single-parameter 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 coverage is 100% with a clear description and example for the accession parameter. The description reiterates its role but doesn't add new constraints or format details, maintaining the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves a single SEC Form 4 filing by accession number, detailing insider, issuer, all transactions, net open-market flow, and SEC link. This distinguishes it from sibling tools like insider.transactions or events.latest.

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 'The full-filing follow-up when insider.transactions or events.latest hands you an accession_number', providing clear when-to-use context. It doesn't include when-not-to-use or other alternatives, but the context is strong.

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 adds context beyond the readOnlyHint annotation by explaining the types of transactions and the effect of the `signal` and `since` parameters. 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 concise, using three sentences to cover purpose and key usage. It front-loads the purpose and then adds parameter guidance without 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?

While the description covers functionality and key parameters, it does not hint at the return structure or pagination, which is important given the absence of an output schema. Also lacks mention of rate limits or authentication.

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 meaning by specifying that `signal` restricts to P/S codes (open-market) and `since` is used for new filings, enhancing parameter understanding.

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 the tool retrieves SEC Form 4 insider transactions, distinguishing between open-market buys/sells, awards, and option exercises. It specifies that data can be retrieved by company ticker or insider name, which differentiates it from sibling tools like insider.clusters or insider.company.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides guidance on using the `signal` parameter to filter open-market trades and the `since` parameter for incremental updates. However, it does not explicitly contrast with alternative insider tools or state when not to use this 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 declare readOnlyHint=true, so the description's addition of FRED context is helpful but not extensive. It does not mention any other behavioral traits (e.g., rate limits, data freshness). The bar is lowered due to annotations, but the description adds moderate value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that is front-loaded with the core action and context. 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?

Given the tool's simplicity (2 params, no output schema, read-only annotation), the description is adequate. It could hint at the output format (e.g., 'observations') but is otherwise 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 both parameters. The description adds extra meaning by providing concrete examples for series_id (e.g., DGS10, CPIAUCSL), which clarifies usage 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 action ('get'), the resource ('recent observations for a macro/economic time series'), and the source ('from FRED') with concrete examples (GDP, CPIAUCSL, DGS10, UNRATE). It effectively distinguishes from sibling tools like macro.series.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?

The description does not provide guidance on when to use this tool versus alternatives. No exclusions or when-not-to-use context is given.

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 'returns matching series IDs and titles' beyond the readOnlyHint annotation, giving useful behavioral context. 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 sentence, front-loaded, every word adds value. No unnecessary 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 search tool, description adequately states purpose and return type. Lacks mention of pagination or no-results handling, but acceptable given simplicity.

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 has 100% coverage with description for 'query' parameter. Description adds specific examples (e.g., 'unemployment rate'), improving understanding 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 verb 'Search', target resource 'FRED macro/economic time series', and output 'matching series IDs and titles'. It distinguishes from sibling 'macro.series.get' which likely retrieves specific series 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?

No explicit guidance on when to use this tool vs alternatives. Usage is implied (when searching by keyword), but no exclusions or comparisons with siblings like 'search' or 'macro.series.get'.

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=true, which is consistent with the description. The description adds behavioral details such as returning null for private/unmatched names, resolution method (alias|exact|fuzzy|unresolved), and the constraint that joins must never key on a wrong ticker. This is 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?

The description is concise, consisting of two well-structured sentences. It is front-loaded with the core purpose and examples, avoids fluff, and efficiently conveys all necessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With only one parameter and no output schema, the description fully covers what agents need to know: input format, output fields (ticker, company name, exchange, resolution method), and edge cases (null for private/unmatched). The use case and constraints are explicitly stated.

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 single parameter 'name' has schema description 'Sponsor / manufacturer name to resolve'. The description adds examples (e.g., 'Janssen Pharms', 'AstraZeneca AB') and explains output behavior, adding meaning beyond the schema. With 100% schema coverage, baseline is 3; the description adds significant value.

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 resolves a pharma sponsor/manufacturer name to its public ticker. It specifies the action, resource, and output, and distinguishes it from guessing with null returns. Examples of input names are provided.

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 states when to use the tool (to join FDA data to financial signals) and what it does not do (return ticker for private/unmatched, never guess). This provides clear usage guidance and differentiation from siblings.

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, so the safety profile is clear. The description adds the sources and implied probabilities, but does not disclose behavioral traits like pagination, rate limits, or whether results are sorted. Minimal extra value 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?

A single, well-structured sentence conveying all essential information without any fluff. Every word 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?

For a simple list tool with no output schema and 3 optional parameters, the description is largely sufficient. However, it omits how the 'limit' parameter interacts with pagination or if there are any maximum limits, leaving minor 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%, so the description does not need to add parameter details. It provides a one-line summary ('Optional keyword filter') that aligns with the 'query' parameter, but adds no new meaning beyond what the schema already states.

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 verb 'List', the resource 'prediction-market contracts', and adds specific context ('implied probabilities', sources 'Polymarket and/or Kalshi'). It distinguishes from siblings like predictionmarket.quote by implying this is for listing all contracts vs. quoting a specific 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?

No guidance on when to use this tool vs. alternatives such as predictionmarket.quote or other list tools. The description does not mention when-not-to-use or provide any context for selection among siblings.

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, so the read-only nature is clear. The description adds that it returns implied probability, but does not cover error handling or edge cases. With annotations present, the description adds sufficient 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?

The description is a single, efficient sentence that front-loads the verb and resource. Every word adds value with 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?

For a simple read tool with two parameters and no output schema, the description fully explains what it does, how it works, and what it returns (implied probability). No additional context is needed.

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 50% (id described, platform missing). The description clarifies both parameters: 'platform + id (Polymarket slug or Kalshi ticker)' adds meaning to platform beyond the enum and reinforces id's format. This compensates for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a single prediction-market contract's implied probability based on platform and ID, using specific verbs and resource. It distinguishes from the sibling 'predictionmarket.list' which lists contracts.

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 implies usage for a single contract quote, contrasting with list tools. However, it does not explicitly state when not to use or mention alternatives, but context from sibling names provides implicit 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, so the read-only nature is known. The description adds value by detailing what the tool returns (origin URL, fetch time, parser version), which goes beyond the annotation. 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?

The description is a single, front-loaded sentence that conveys all essential information without unnecessary words. Every element 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 read tool with two well-documented parameters and no output schema, the description completely covers the return value. No gaps remain.

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 both parameters having descriptions. The description does not add parameter-specific meaning beyond what the schema provides, so 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?

The description uses a specific verb ('return'), identifies the resource ('source record(s) for a datapoint'), and lists key fields (origin URL, fetch time, parser version). It distinguishes the tool from siblings by framing it as a trust layer for citing primary sources.

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 implies usage when an agent needs to cite primary sources, but does not explicitly state when not to use it or name alternatives. The context is clear enough for correct selection.

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, so the description's consistency with a lookup operation is expected. The description adds value by specifying the output (SEC CIK or slug) though it does not discuss rate limits or failure modes, which is acceptable given low complexity.

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. The first sentence immediately states the core purpose, and the second adds context and examples, achieving excellent conciseness and front-loading.

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 single parameter, no output schema, and clear annotations, the description fully informs an agent about the tool's function, input expectations, and output type (CIK or slug). No gaps are apparent.

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 the 'q' parameter described as 'Search query'. The description adds meaningful concrete examples (e.g., 'Berkshire', 'Citadel'), enhancing the schema's generic 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?

The description uses specific verbs ('resolve', 'turn into') and clearly identifies the tool as an entity-resolution entry point for funds and managers, distinguishing it from sibling tools that assume an identifier is already known.

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 states the tool is the entry point for entity resolution and implies its use before fund.* tools, providing clear context. However, it does not explicitly advise against using it for other purposes or mention 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 already mark it read-only. Description adds valuable behavior: 'joined on ticker — never a fuzzy name match', 'congress $ are amount-range midpoints (approximate)', and mentions a verdict that escalates to triple_confluence_buy. These details go beyond annotations and inform agents about data precision and output structure.

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 verbose and uses informal language ('The moat join'). It front-loads the concept but contains redundant explanations. Could be shortened to clearer, more direct sentences without losing meaning.

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 and moderate complexity (5 params, 2 modes), the description explains data sources, join method, the verdict concept, and approximate nature of congress amounts. It covers the main usage scenarios adequately, though the exact return structure is implied rather than explicit.

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 5 parameters with descriptions. The description mentions 'Insider open-market lookback window' matching schema but adds no new semantic details. It restates the ticker usage in context but does not explain formats, constraints, or relationships beyond what 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?

Description clearly states the tool finds confluence among insider, institutional, and congressional trades. It specifies two distinct modes (per-ticker and market-wide) with explicit verbs 'pass a ticker' and 'omit ticker'. This differentiates it from siblings like 'get_ticker_confluence' and 'insider.transactions' by focusing on the triple-signal aggregation.

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 clear instructions: pass a ticker for per-name analysis, omit for market-wide ranked list. Implicitly tells when to use each mode. However, it does not explicitly compare to sibling tools or state when not to use this tool, leaving some decision ambiguity for agents.

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?

Consistent with readOnlyHint annotation, adds that rankings are by fund agreement and data comes from latest 13F filings. 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 front-loaded purpose, no fluff. Could be slightly more structured but overall 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?

Adequate for a two-parameter tool with no output schema; explains relationship to stock.owners, which provides helpful cross-tool 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 has 100% coverage; description adds meaning to each mode (e.g., 'bought' = NEW/ADDED cluster-buys) and clarifies limit range, exceeding schema detail.

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 surfaces cross-fund consensus from 13F filings with three modes (held, bought, sold) and specifies it is the inverse of stock.owners, distinguishing it from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Each mode is explained with examples (e.g., 'held=consensus longs'), and the inverse relationship to stock.owners is noted. Lacks explicit when-not-to-use guidance but is clear enough for agent selection.

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. Description adds output fields but no extra behavioral traits beyond data scope.

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?

Concise two-sentence description with front-loaded core purpose and relevant detail.

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?

Adequately describes output data for a simple read-only list tool; minor lack of pagination detail is 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 coverage is 100%; description does not add parameter-specific details 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?

Clearly states the tool fetches institutional 13F owners for a stock, listing specific data fields. Distinguishes from siblings like fund.holdings and 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?

Implicitly indicates when to use: to find 'who owns this stock'. No explicit exclusion criteria or alternatives, 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?

The description aligns with the readOnlyHint annotation, confirming it is a read operation. It discloses key behaviors: standard freshness (≤24h), returns events with SEC source URLs, and workspace-specific curation. 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?

The description is well-structured, front-loading the core purpose. It contains several sentences, each adding value, but slightly verbose. Could be trimmed without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description does not define the structure of returned events. While it mentions 'each event carries its SEC source URL' and filing types, the lack of an output schema means the description should provide more detail on the event format for complete 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% and the description adds meaningful context: 'since' is a cursor from a prior response, omitting it gives the latest events; 'limit' restricts count. This goes beyond mere schema definitions.

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 uses a specific verb ('Poll') and identifies the resource ('THIS workspace's watchlist'). It clearly states the tool polls for new SEC Form 4 filings since a cursor, distinguishing it from sibling tools like watchlist.poll.live.

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 explains when to use the tool (for a watch loop) and how to use the 'since' parameter for incremental polling. However, it does not explicitly contrast with sibling tools like watchlist.poll.live, though the context implies a difference in freshness (standard vs. live).

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 pricing plan requirement and live freshness (within minutes of SEC acceptance), adding behavioral context beyond the readOnlyHint annotation. 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?

Two sentences front-load the core purpose and follow with key details (pricing, sibling differentiation). No extraneous text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all essential aspects: purpose, when to use, pricing, cursor behavior. Lacks explicit mention of return format, but for a polling tool with cursor semantics, the description is reasonably 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% with clear descriptions for both parameters. Description adds only minor context about cursor semantics, not significantly improving understanding 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?

Clearly states it is a live version of watchlist.poll, with specific verb and resource, and distinguishes from its delayed sibling by emphasizing 'LIVE freshness' and minute-fresh 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 specifies when to use this tool (Developer/Pro plan) versus the alternative watchlist.poll for delayed data, along with scope and cursor semantics.

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