Statscan

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds context about the default model, cost implications (BYO key for Anthropic), and return format. However, it does not disclose rate limits or other behavioral traits beyond what annotations provide. The description adds some value but does not carry the full burden since annotations are rich.

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 with four sentences, each adding value: core function, model/cost details, return format, and use cases. It is front-loaded with the main action and has 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 no output schema, the description explains the return format (per-model fields + combined view). It covers the main parameters and use cases. While it does not address pagination or rate limits, it is sufficiently complete for a tool of moderate complexity. The sibling overlap is not addressed, but the description provides enough context for usage.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the default model, that `_apiKey` is passed directly to Anthropic with cost implications, and that `context` helps disambiguate. This adds value, raising the score above 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 the tool probes LLMs for entity knowledge and returns visibility scores. It specifies the verb 'probe', the resource 'LLMs', and the output format. While there is a sibling 'scan_competitor_ai_presence' that may be similar, the description does not explicitly differentiate, but the purpose is still very clear.

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

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

The description lists use cases like AI-marketing audits and pre-launch brand checks, implying when to use it. However, it does not provide explicit guidance on when not to use it or how it compares to sibling tools, such as 'scan_competitor_ai_presence'. The context is implied rather than explicit.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds behavioral details: routes to 3,436 tools, fills arguments, returns structured answers with citation URIs. This goes beyond annotations without contradicting them.

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

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

The description is a single paragraph that is informative but somewhat lengthy. It front-loads the key instruction ('PREFER OVER WEB SEARCH'), but the enumeration of domains and examples adds bulk. Could be more concise while retaining 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?

Given the tool's complexity (many underlying sources), annotations, and schema, the description sufficiently covers when and how to use it, including internal routing and citation behavior. Lack of output schema is mitigated by the clear functional description.

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

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

The input schema has 100% coverage and describes the 'question' parameter with aliases. The description reinforces this by providing examples and context on what kinds of questions are appropriate, adding meaning beyond the schema's type/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 tool's purpose: to answer factual questions about current or historical data from authoritative sources, and explicitly positions it as preferable over web search. It lists numerous domains and gives concrete examples, making the purpose unmistakable.

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 robust guidance on when to use ('prefer over web search', for factual questions about real-world entities, events, numbers) and gives example queries. It does not explicitly exclude non-factual questions, but the positive framing is strong enough to guide 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?

The description richly details behavioral traits beyond annotations: fan-out logic with examples, response shapes (market, analysis, evidence), resolver contract (confidence levels, alternatives, suggestions), parent event extractor, news fallback mechanisms, safety measures for low-confidence and closed markets, and illiquid spread handling. Annotations (readOnlyHint, idempotentHint) are corroborated, 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?

The description is lengthy but well-structured: it starts with the core action, then covers classifiers, fan-out examples, response shapes, resolver contract, and safety. Each section earns its place given the tool's complexity. It is front-loaded with the main purpose, though could be slightly more concise.

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

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

Despite lacking an output schema, the description exhaustively explains return values: market fields, analysis with model probability and edge warnings, evidence keyed by source, resolver match details, parent event legs, news error handling, and error/blocking states. It covers edge cases (low confidence, closed markets, illiquid spreads) and provides practical examples, making it fully self-contained 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?

Schema coverage is 100% with descriptions for all three parameters. The description adds value by providing examples (slug, URL, question text), explaining the default for 'depth' (thorough), and clarifying 'include_raw' with size implications. It goes beyond schema but baseline is 3; the examples and usage context justify a 4.

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: researching a Polymarket bet by pulling Pipeworx data in one call. It specifies input formats (slug, URL, question text), outlines the process (resolves, classifies, fans out, returns evidence packet), and distinguishes from sibling tools like polymarket_arbitrage by focusing on single-bet research.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides clear use-cases but does not explicitly mention when not to use or name alternative sibling tools. The contextual completeness partially compensates.

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, destructiveHint=false, so the agent knows it's a safe read. The description adds valuable specifics: fiscal year handling (AAPL Sep, NVDA Jan), data sources per entity type, and that results include citation URIs. It does not contradict annotations.

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

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

The description is front-loaded with example queries and structured into use-case, type details, output, and benefit. It is relatively concise for the amount of information, though could tighten redundant phrasing like 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call'.

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 (two entity types, fiscal year nuances) and the lack of an output schema, the description adequately covers return format ('paired data + pipeworx:// citation URIs') and key behavioral traits. It does not explain error cases, but for a limited-entity comparison tool, this 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% (both parameters described). The description adds context: 'type' enum values are explained (company vs drug), and 'values' includes examples and constraints. It goes beyond the schema by explaining what data is fetched for each type and how fiscal years are handled.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It provides example queries like 'X vs Y' and specifies data sources (SEC EDGAR for companies, FAERS for drugs). It differentiates from siblings by recommending this tool over sequential single-entity lookups.

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

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

Explicit guidance is given: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also explains that results are sorted by primary metric, aiding interpretation. No exclusions are needed given the clear use case.

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

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

Annotations already declare readOnlyHint and idempotentHint; description adds that results include full input schemas with examples, ready to call directly. No contradictions. Adequate behavioral context beyond annotations.

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

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

Two sentences packed with information, front-loaded with purpose and usage. Every sentence is essential with no fluff.

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

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

Given no output schema, description explains return (top-N tools with names, descriptions, schemas). Covers when to call and return format. Minor gap: no mention of error handling or empty results, but adequate for a discovery 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%. Description adds value by explaining the query parameter accepts natural language and lists aliases (q, task, search, description). This helps the agent understand all input options.

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 tools by describing data or task, with specific examples of domains (SEC filings, stocks, etc.). It distinguishes from sibling tools by being a meta-discovery tool, not a data-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?

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Also provides scenarios like browsing and searching. Does not specify when not to use, but context is sufficient.

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, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), notes the patent API sunset and soft-fail behavior, and specifies the return fields. This goes beyond what annotations provide.

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

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

The description is lengthy but well-structured: starts with examples, then states preference, then lists sources and return format. Every sentence adds value, though some consolidation could improve conciseness.

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 details the return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It also mentions limitations (no name support, patent API sunset). This is sufficient for an agent to understand what the tool provides, though more detail on error handling would improve it.

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

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

Input schema has 100% parameter description coverage, so baseline is 3. The description adds extra detail: value must be ticker or zero-padded CIK (not names), and type is currently restricted to 'company'. This improves parameter understanding beyond the schema alone.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company' and gives multiple example queries. It distinguishes itself from sibling tools like resolve_entity (which handles name resolution) and from chaining multiple single-purpose lookups, making its purpose unambiguous.

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

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

The description explicitly says to prefer this tool over chaining single-pack lookups for holistic views, and instructs to use resolve_entity when only a company name is available. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations confirm destructiveHint=true and idempotentHint=true. Description adds context about clearing stale data but doesn't clarify behavior when key doesn't exist or side effects beyond deletion.

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 efficient sentences: first states purpose, second gives usage guidelines. 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?

For a simple one-parameter deletion tool with annotations, description covers purpose and when to use. Could mention behavior for missing keys or confirmation of deletion, but overall adequate.

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

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

Schema coverage is 100% for the only parameter 'key'. Description simply repeats 'Memory key to delete', adding no new meaning beyond the schema.

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

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

Description clearly states 'Delete a previously stored memory by key' with specific verb and resource. It mentions pairing with siblings 'remember' and 'recall' but doesn't explicitly differentiate them.

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 when to use ('context is stale, task is done, clear sensitive data') and suggests pairing with remember and recall, providing clear context and 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 provide key behavioral traits (read-only, idempotent, non-destructive, open-world). Description adds that it fetches the page, extracts title/description/key links, and outputs markdown, but does not disclose potential failure modes or rate limits. With annotations covering safety, a 3 is appropriate.

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 a single paragraph of ~60 words, front-loaded with the primary action and output. Every sentence adds value: purpose, process, output location, and use cases. No redundancy 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?

Despite lacking an output schema, the description states the output is 'a single text blob ready to drop at site-root/llms.txt', which is sufficient. It explains the internal process (fetch, extract, emit) and covers essential context for a simple tool. No critical 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?

Input schema has 100% description coverage for both parameters (url and max_links). Description mentions 'Full URL' and 'Maximum number of link entries', but adds no new semantic detail beyond what the schema already provides. Baseline 3 is correct.

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 explicitly states the tool generates llms.txt for a URL, mentions use cases (indexing, drafting, auditing), and differentiates from sibling tools which cover different domains (betting, entity profiles, etc.).

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 lists three specific use cases (client indexing, own project drafting, competitor auditing), providing clear context for when to use. However, it does not explicitly state when not to use or mention alternative tools, though no obvious alternative exists 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 indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds that the tool lists 'new release' changes and is for scheduled refreshes, but this is context beyond what annotations provide. It does not contradict annotations.

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

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

The description is two sentences, front-loaded with the core action (list of series that changed), then the default, then a use case. Every sentence adds value without redundancy. It is appropriately sized.

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 optional parameter, high schema coverage, and presence of output schema, the description provides sufficient context. It explains what the tool does, the default, and a practical use case. No gaps remain for this simple 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 one optional parameter 'date' described as 'YYYY-MM-DD (default today)'. The description reaffirms the default but adds no new semantic meaning beyond the schema. Since schema coverage is high, 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 lists series that changed on a given date, with a default of today. The verb 'list' and resource 'series that changed' are specific, and the scope is defined by date. This distinguishes it from siblings like 'recent_changes' by focusing on new releases and cubes.

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 mentions it is useful for detecting updated cubes for scheduled refreshes, providing a use case. However, it does not explicitly state when to use this tool versus alternatives, nor does it exclude any scenarios. The guidance is implicit rather than explicit.

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 idempotent, read-only, nondestructive. Description adds that it gives a URL, not a file, clarifying behavior 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?

Two sentences, front-loaded with core purpose, no unnecessary words. Every sentence adds value.

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

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

Covers main behavior and source. Output schema exists to document return format, so description doesn't need to. Missing details about URL expiration or availability, but acceptable for a straightforward URL generator.

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 provides full descriptions for both parameters (language and product_id). Description adds no extra meaning beyond schema, so 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?

Description clearly states the tool returns a URL for the cube as CSV download, using specific verb 'Return' and resource 'StatCan-hosted URL'. It distinguishes from siblings by noting it doesn't fetch the file, which differentiates it from data retrieval tools like get_latest_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?

Implicitly tells when to use: when a download URL is needed, not the data itself. Could be more explicit about alternatives, but the contrast with fetch tools is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds valuable behavioral context: the tool returns dimensions, member trees, frequency, geography, and last release, and explains its role in constructing coordinate strings. 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 consists of two concise sentences. The first sentence specifies the action and content; the second states the purpose. No extraneous information. It is front-loaded and earns each sentence.

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 presence of an output schema (not shown but mentioned), the description covers the key fields (dimensions, member trees, frequency, geography, last release) and links to `get_latest_data` for context. No missing critical information for a metadata retrieval 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?

The input schema covers 100% of the single parameter `product_id` with a description including type and example. The description does not add new parameter semantics beyond reiterating the example value. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states 'Fetch full metadata for a cube' and lists specific metadata types (dimensions, member trees, frequency, geography, last release). It also distinguishes from sibling tool `list_cubes` by implying this fetches detailed metadata vs. a list, and connects to `get_latest_data` for coordinate string construction.

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 'Use to figure out a coordinate string for get_latest_data', providing a clear use case. It implies it is a prerequisite for `get_latest_data`, but does not explicitly exclude other uses or mention alternatives like `list_cubes` for discovering cube IDs.

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 read-only, idempotent, non-destructive. Description adds important behavioral details: coordinate format, trailing zeros, and relation to get_cube_metadata.

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

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

Three sentences, no redundancy, front-loaded with key info. Every sentence adds value.

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

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

Given output schema exists, description doesn't need return details. Covers coordinate specification well, but could mention that input is for a single series only.

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%, baseline 3. Description adds meaning by explaining the coordinate format and trailing zeros convention, which is not 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?

Clearly states the action (get) and resource (latest N observations for a specific series within a cube). Distinguishes from sibling tools like get_changed_series and get_cube_metadata.

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 context: when to use (latest observations) and prerequisite (use get_cube_metadata to map members to positions). Does not explicitly exclude cases but gives enough 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 cover read-only and idempotent aspects; description adds response size and client-side handling advice, enhancing transparency.

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

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

Two sentences, no wasted words, front-loaded with purpose, highly efficient.

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

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

For a tool with zero parameters and existing output schema, description provides all necessary context including response size hints.

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

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

No parameters, schema coverage 100%, baseline 4 applies; description doesn't need to add parameter info.

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 'List all available cubes' with specific fields, distinguishing it from sibling tools like get_cube_metadata.

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 using productId with other tools and provides caching/filtering guidance for large response, but no explicit alternative or when-not-to-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?

Disclosures beyond annotations include rate limits (5 per identifier per day), being free, not counting against tool-call quota, and that team reads digests daily. 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?

Single paragraph that front-loads purpose, then usage, then constraints. Every sentence 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?

Covers purpose, usage, parameters, constraints, and team process. Could mention what happens after submission (e.g., acknowledgment), but given the simplicity, this is adequate.

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 good descriptions, but the description adds value by explaining the enum categories more contextually and giving guidance on message content (be specific, 1-2 sentences).

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

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

The description clearly states the tool's purpose: sending feedback about bugs, feature requests, data gaps, or praise. It distinguishes from sibling tools by being a feedback mechanism, which is unique among the listed 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?

Provides explicit guidance on when to use each feedback type (bug, feature/data_gap, praise) and what not to do (don't paste end-user's prompt). Also mentions rate limits and quota.

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?

Adds significant context beyond annotations: data source (CF analytics-engine), no PII, caching behavior (5min-1h), self-aggregating signal. No contradictions with readOnlyHint, idempotentHint, destructiveHint.

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?

Six sentences, front-loaded purpose, uses bullet-like structure for use cases. Could be slightly tighter but still very clear and well-organized.

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

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

Given no output schema, the description adequately explains the return: top tools, top packs, total call volume. Also covers derivation, caching, and privacy. Complete for a simple trending 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?

Only one parameter (window) with enum and schema description. The description adds meaning by explaining the tradeoff between shorter and longer windows, complementing 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 returns top tools, packs, and total call volume over a recent window, with three specific use cases. It distinguishes itself from sibling tools by focusing on trending/aggregated signal derived from agent activity.

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

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

Explicitly provides three scenarios for when to use the tool. Does not explicitly mention when not to use or alternatives, but the context is clear enough from the description and sibling tools.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds rich behavioral details: monotonicity checks, partition sum validation, similarity thresholds, placeholder filtering, and response 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?

Front-loaded with requirement, structured into modes and filters. Slightly verbose but every sentence adds value; thresholds and details aid agent understanding.

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 response fields (opportunities[], gap_pp, suggested_trade, etc.) and partition_check details, covering all aspects for a 2-parameter 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. The description adds meaningful context: examples of event slugs and topic seed questions, plus behavioral differences between modes.

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 'finds arbitrage opportunities on Polymarket' via specific methods. It distinguishes from siblings like 'polymarket_edges' and 'polymarket_kalshi_spread' by focusing on internal arbitrage detection.

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 'REQUIRES one of `event` or `topic` — call with no args fails.' Recommends event mode for specific markets and topic mode for cross-event scanning, providing clear usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, making the safety profile clear. The description adds substantial behavioral context: caching behavior ('Cached 1h at the KV level keyed on all knobs'), detailed model families and their data sources, and the structure of the response including diagnostics. This goes beyond what annotations provide, earning a 4.

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 very long and dense, filled with technical acronyms and detailed explanations of model families. While it is well-structured with clear sections, it is not concise for an AI agent. Every sentence earns its place, but the length makes it harder to quickly grasp the core functionality.

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 (9 parameters, no output schema), the description is complete. It covers all three segments, response structure (by_segment, fed_candidates, _diagnostics), caching, and how knobs affect the output. The agent can fully understand what the tool returns and how to interpret the results.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the purpose of knobs like min_liquidity and min_partition_leg_kelly in context, clarifying how they filter opportunities. For example, min_partition_leg_kelly is explained as applying to per-leg Kelly inside top_legs, which is not obvious from the schema alone.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the verb 'scan' and resources 'top Polymarket markets' and further distinguishes itself by detailing three segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) which set it apart from sibling tools like polymarket_arbitrage and polymarket_kalshi_spread.

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 usage context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains when to use filters like min_liquidity and max_spread_pp, and mentions Fed bets surface but are excluded from ranking. However, it does not explicitly exclude sibling 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?

The description adds substantial behavioral context beyond annotations: it details compatibility warnings for non-equivalent bet shapes, temporal alignment checks, skipped comparison counters, and the rarity of meaningful spreads. No contradiction with annotations (readOnlyHint=true, idempotentHint=true).

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 informative but verbose, with multiple paragraphs and long sentences. It is well-structured with sections (TWO MODES, RESPONSE, SAFETY FIELDS), but could be tighter to reduce token usage.

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 fully covers the output structure (leg prices, spreads, safety fields) despite no output schema. It explains all edge cases (compatibility warnings, temporal alignment, skipped counters) and sets expectations for rarity of tradeable spreads.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by listing the 10 pre-mapped topic strings and explaining that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, which aids agent 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?

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit pairings) and distinguishes its focus from siblings like polymarket_arbitrage by naming the specific venues.

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 explains two usage modes (topic vs explicit) and provides guidance on when spreads are meaningful (compatibility warnings, temporal alignment). It warns that pre-mapped topics often are not tradeable, but does not explicitly contrast with alternative tools.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds valuable context: scoping to an identifier (anonymous IP, BYO key hash, account ID) and the relationship with 'remember' and 'forget'.

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, well-structured, and front-loaded with the main action. Every sentence adds value without fluff.

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

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

Given the simplicity of the tool (single optional parameter, no output schema), the description fully covers behavior: retrieving a value or listing keys, scoping, and relationship with sibling tools. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats that omitting the key lists all keys, which matches the schema description. No additional semantic information beyond schema is provided.

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 verb 'retrieve' and the resource 'value previously saved via remember', and distinguishes it from siblings 'remember' and 'forget'. It also specifies the alternative behavior of listing all keys when the argument is omitted.

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

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

The description provides clear when-to-use guidance with examples (user's target ticker, address, research notes) and mentions pairing with 'remember' and 'forget'. However, it does not explicitly 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 and idempotentHint, so the description focuses on additional behavioral details: fan-out to multiple sources (SEC, GDELT/GNews, USPTO), soft-fail for USPTO due to API sunset, and return structure. This adds value beyond annotations but could mention rate limits or error handling more explicitly.

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 efficient, with each sentence contributing to understanding. It is front-loaded with purpose and examples. The length is appropriate given the complexity (multiple data sources, parameter options), with no redundant information.

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

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

Although there is no output schema, the description adequately explains the return format (structured changes grouped by source, total_changes count, citation URIs). It covers the multi-source fan-out and fallback behavior, leaving no significant gaps for an agent to select or invoke the tool correctly.

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

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

With 100% schema description coverage, baseline is 3. The description adds significant value by detailing the `since` parameter format (ISO date vs relative shorthand with examples), recommending default values ('30d' or '1m'), and clarifying `type` constraints and `value` format. This justifies a 4.

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 function as a change feed aggregator for a company, using concrete example queries ('What's new with X', 'latest on Y'). It explicitly distinguishes from the sibling tool entity_profile, which provides static profiles instead of recent changes.

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 detailed guidance on when to use the tool, including example queries and context-specific scenarios. It explicitly states when not to use it ('Use entity_profile instead...') and explains the fallback mechanism between GDELT and GNews.

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 details beyond annotations: key-value pairs scoped by identifier, persistence duration (24h for anonymous sessions). Annotations already show idempotentHint=true and destructiveHint=false, but description clarifies mutability and 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?

Four sentences, each with a distinct purpose: what, when, how, and pairing instructions. No redundancy 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 key-value store tool with only 2 parameters and no output schema, the description covers all necessary aspects: purpose, usage, storage details, and lifecycle.

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 100% coverage with descriptions for both parameters. The description reinforces their purpose but adds no new details 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 that the tool saves data for reuse across conversations or sessions, with specific examples like tickers and addresses. It distinguishes from siblings 'recall' and 'forget', which are listed in 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?

Explicitly says 'Use when you discover something worth carrying forward' and mentions pairing with recall and forget for retrieval and deletion, providing clear guidance on when and when not to 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?

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's safe and non-destructive. The description adds behavioral context by stating that 'each call cascades through several lookup endpoints internally,' which discloses internal complexity beyond what annotations provide. No contradictions detected.

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 efficient and front-loaded with examples, then states purpose, usage guidance, and supported types. Every sentence adds value, though it could be slightly more concise. It avoids repetition of schema 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?

Given the tool has 2 parameters and no output schema, the description adequately covers what the tool does, what it returns for each type, and example inputs. It explains return fields (ticker, CIK, RxCUI, citations) and mentions auto-disambiguation for companies. It feels complete for its complexity, though it could mention error handling or edge 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%, but the description adds significant meaning beyond the schema. For the 'type' parameter, it explains what each enum value returns (e.g., company returns ticker, CIK, company name, citation URI). For 'value', it provides concrete examples and format details (e.g., 'AAPL', '0000320193', 'ozempic'). This surpasses 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?

The description uses specific verbs ('resolve', 'look up') and clearly states the tool's unique role: mapping user-spoken names to canonical identifiers required by other tools. It explicitly mentions use cases ('pick one for me') and distinguishes from sibling tools by positioning it as the first step when a name is known but an ID is needed.

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 guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains when to use the tool and implies that if you already have the ID, you likely don't need this tool. The supported types are clearly listed, with distinct return formats, aiding appropriate 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?

Description discloses probing each entity with ai_visibility_check, ranking by score, and returning a ranked list with score, confidence, signal density. Annotations (readOnlyHint, idempotentHint) are consistent.

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

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

Three sentences, front-loaded with purpose, no redundant information.

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

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

For a comparative tool with no output schema, the description adequately describes the return value (ranked list with metrics) and covers all necessary context.

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

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

Schema coverage is 100%, but description adds meaning: first entity is 'subject', rest are competitors; notes that omitting models defaults to workers-ai.

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

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

The description clearly states the tool's purpose: compare AI visibility across multiple entities side-by-side. It uses specific verbs and resource, and distinguishes from sibling tools like ai_visibility_check and compare_entities.

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

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

Provides explicit use case: competitive AI-marketing audits. Does not state when not to use or compare to alternatives, but the context is clear enough for an AI agent to decide.

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

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

Annotations already indicate readOnly/idempotent/non-destructive. Description adds valuable behavioral context: composite call fanning out to two services, partial failures degrade gracefully, and bundlephobia's first measurement can take 5-30s. 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 moderately long but well-structured with front-loaded purpose. Every sentence adds value, though it could be slightly tighter. Still effective and not overly verbose.

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 (composite, external calls, partial failures, multiple data sources), the description is thorough. It details return fields, failure modes, ecosystem scope, and timing caveats. No output schema, but return structure is sufficiently described.

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 good descriptions for both parameters (package and version). The description doesn't add new semantic meaning beyond schema, but reaffirms that version defaults to latest. Baseline 3 is appropriate since schema handles it well.

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 a composite check for npm packages, combining deps.dev and bundlephobia to answer questions about safety, popularity, and size. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on package dependencies.

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

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

Explicit guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". Also notes ecosystem limitation (NPM only) and alternatives for other ecosystems, providing clear when-to-use and when-not-to-use 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 readOnly, idempotent, openWorld, and non-destructive. The description adds behavioral context: it only supports company-financial claims via SEC EDGAR + XBRL, and lists the return types (verdict options, structured form, citation, delta). 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 a single dense paragraph, front-loaded with example queries, and each sentence adds value (purpose, domain, returns, efficiency). Could be slightly more structured, but 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 (1 parameter, no output schema), the description is thorough: it explains purpose, usage, domain, return components, and why it's efficient. No gaps remain for the intended use case.

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 provides rich examples of the 'claim' parameter (e.g., 'Apple's FY2024 revenue was $400 billion'), adding meaning beyond the schema's description of a natural-language factual claim.

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 performs natural-language claim verification for factual accuracy, with explicit example queries. It specifies the domain (company-financial claims for public US companies via SEC EDGAR + XBRL), distinguishing it from siblings like entity_profile or compare_entities.

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 use 'whenever the agent needs to check whether something a user said is factually correct' and defines the supported claim type. While it doesn't explicitly state when not to use it or name alternative tools, the domain boundary is clear and it mentions replacing 4-6 sequential calls, implying specific context.

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