Ecos Kr

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds return structure details and model cost implications, but does not mention external API call behavior or potential delays.

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, front-loaded with purpose, and every sentence adds value. 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 tool with 4 parameters and no output schema, the description explains output format and gives usage examples. It is complete for the complexity, though error handling or missing key behavior is not addressed.

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?

All parameters have descriptions in the input schema (100% coverage). The description adds context on default model and API key usage, but does not significantly extend beyond the schema for parameter meaning.

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 knowledge about an entity and returns a visibility score. It mentions use cases like AI-marketing audits, but does not explicitly distinguish from sibling tools like 'scan_competitor_ai_presence' which may have similar functionality.

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 (for visibility checks) and how to probe different models (default free Workers AI, additional Anthropic with key). It provides clear context but does not specify when not to use or mention 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 mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds useful behavioral detail beyond that: it routes to one of 5,738 tools across 1,499 verified sources, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. 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 long but front-loaded with the most important instruction: 'PREFER OVER WEB SEARCH'. It packs many useful details—domains, examples, routing behavior, and sibling alternatives—without fluff, though it could be slightly tighter.

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 broad routing tool with no output schema, the description is highly complete: it covers supported domains, trigger phrasing, example queries, routing to 5,738 tools, citation-URI return behavior, and explicit guidance for when to use sibling tools instead. Nothing essential for invoking it correctly appears missing.

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

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

The schema already documents all six parameters at 100% coverage, including the `question` parameter and its aliases, so the baseline is 3. The description adds value by explaining acceptable question types, domains, and providing multiple concrete examples, which helps an agent form effective queries even though it adds no syntax-level 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?

The description clearly identifies the tool as a fact-lookup router that should be preferred over web search for current or historical data across many enumerated domains, returning answers with citations. It distinguishes itself from siblings by naming ask_pipeworx_grounded, ask_pipeworx_beta, and deep_research and explaining what each is for.

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 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', and gives concrete trigger phrases such as 'what is', 'look up', 'find', and 'get the latest'. It also states when to use alternatives: ask_pipeworx_grounded/beta for single-source verbatim answers and deep_research for broad multi-part questions.

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, idempotent, and non-destructive; the description goes further by disclosing that candidate routing improvements are enabled live during tests, that none is active as of a specific date, and that it falls back to nothing—meaning it is a complete router, not a degraded wrapper. This accurately frames the beta/dynamic nature without contradicting any 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?

Four sentences each carry information: beta identity, current state, usage instruction, and fallback status. The description is front-loaded with the beta relationship to ask_pipeworx and scoped with a specific date for the last retired candidate. There is minor redundancy between 'identical' and 'matches ask_pipeworx exactly,' but nothing extraneous.

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 beta clone of an existing router, the description covers what changes (routing candidates), when it changes (only under test), the current state, and how to invoke it (like ask_pipeworx). It also states that the response shape matches ask_pipeworx, which mitigates the lack of an output schema. It relies somewhat on the agent knowing ask_pipeworx's exact behavior, but that is a reasonable dependency given the sibling tools list.

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

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

The schema already has 100% coverage, with aliases q, text, and input pointing to the required question, so the description does not need to repeat parameter meaning. It adds the useful cross-reference 'same arguments' as ask_pipeworx, but does not itself define the question parameter beyond what the schema provides. Baseline 3 is appropriate given the 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 first sentence names the tool as 'Beta version of ask_pipeworx' and describes it as an identical universal router with the same 5,738 tools, arguments, and response shape. It goes on to confirm it is a full working router rather than a fallback, making the purpose clear and distinguishing it from stable ask_pipeworx and the grounded sibling.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide merges. This gives a concrete condition for choosing this tool over the stable sibling. It also notes that with no candidate active it currently matches ask_pipeworx exactly, which helps an agent decide whether behavior differs today.

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

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

Beyond the readOnly, openWorld, idempotent, and non-destructive annotations, the description discloses the full success return contract, five explicit refusal reasons, and the behavior of extracting only from tool results. This significantly enriches the agent's understanding of how the tool behaves, including its refusal capabilities and added LLM-call cost.

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 core purpose and then efficiently covers routing, return shape, refusal behavior, usage guidance, and cost tradeoff. Every sentence earns its place and the structure flows from what the tool does to when to use it.

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

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

There is no output schema, so the description properly documents the exact return object and refusal reasons. It also explains routing behavior, the source scope, cost implications, and usage boundaries, making it complete for an agent to decide whether and how to call the 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 schema already documents the question parameter and its aliases, and schema description coverage is reported at 100%, so the description does not need to add parameter-level detail. The description adds no extra meaning about the parameter itself, only about tool behavior, which is already covered elsewhere. 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 states a specific, distinct purpose: a hallucination-resistant answer mode that extracts answers only from fetched tool results and refuses when the source does not answer. It explicitly contrasts itself with ask_pipeworx, making it easy for an agent to distinguish this grounded mode from the regular mode.

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

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

The description gives explicit when-to-use guidance: whenever answers will be quoted, cited, or acted on, or when the agent must not invent facts, with concrete domains like financial verdicts, legal claims, medical lookups, and public statements. It also states the cost tradeoff and tells the agent to prefer ask_pipeworx for casual lookups.

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, idempotentHint, openWorldHint, destructiveHint false. The description adds significant behavioral detail: resolution process, fan-out logic, low-confidence short-circuit, closed/dead market handling, wide spread indicators, resolution-rule risk (cancellation rule), and parent event extraction. 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 very long but well-structured with labeled sections (USE, CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and front-loaded with purpose. Every sentence adds value, but it could be more concise. Still, the structure aids comprehension.

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

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

Given the complexity (3 parameters, no output schema), the description is remarkably complete. It covers response shapes, resolver contract, parent event extractor, news fields, safety paths, resolution-rule risk, and multiple edge cases. It compensates fully for the lack of output schema by describing what the agent can 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%. The description explains each parameter beyond the schema: market can be slug/URL/question text; depth explains quick vs thorough with evidence source counts; include_raw details payload size and use cases. Examples are provided for market. This adds meaning for correct invocation.

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

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

The description opens with a clear verb+resource statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text), outlines the workflow (resolve, classify, fan out, return evidence packet and comparison), and lists classifiers and fan-out examples. This fully distinguishes it from sibling tools like ask_pipeworx or deep_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?

Explicit use cases are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides guidance on when to inspect fields and when to trust outputs (e.g., check market_match_confidence before trusting analysis). The description includes blocking conditions and edge-case handling, making usage context 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 readOnly, openWorld, idempotent, non-destructive. Description adds: off-calendar fiscal year handling, sorting by primary metric, efficiency (replaces 8-15 lookups). 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?

Starts with example queries for easy recognition, then explains behavior. Fairly long but every sentence adds value. Could be slightly more concise, but 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?

With full annotation coverage and complete schema descriptions, the description adds essential context on data sources, sorting, and efficiency. Outcome is clear for an agent.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning by linking type to specific data sources (EDGAR/XBRL for company, FAERS for drug) and explains values constraints (tickers vs names, 2-5 items).

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

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

States specific verb 'Compare' and resources (companies/drugs), with clear distinction from sequential lookups. Example queries make it immediately recognizable.

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 urges preference over sequential single-pack lookups and provides trigger phrases. Differentiates company vs drug use cases with concrete data sources.

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

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

The description goes far beyond annotations. It discloses: requires sign-in and paid plan for thorough, latency expectations (15-60s, up to ~90s), returns gaps[] for unanswered facets (never invented), conditions for contradictions[], semantic excerpting behavior, hop field, and citation_uri fetchability. This is exceptionally transparent about behavior and edge cases.

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

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

Dense but well-structured: starts with the most critical constraint (account required), then core mechanism, then use cases, then exclusions, then depth-specific behavior. Every sentence carries unique information. Slightly long (single paragraph), but each sentence earns its place given the complexity of the tool's behavior.

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?

Complete for a research tool with no output schema. The description explains return format (findings packet with verbatim evidence, confidence, source, fetched_at, citations), how depth levels behave, failure modes (gaps[]), latency, prerequisites, and alternatives. An agent could accurately invoke this tool and interpret its results without additional 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%, so baseline is 3. The description adds meaningful context beyond the schema: depth affects facet count, gap-recovery hop, contradictions scan, and paid plan requirement. question param is well described in schema; description adds the breadth/multi-part usage context. The only minor gap: no explicit example values for depth, but the schema enum covers the values and description explains their effects in 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?

States specific verb+resource: grounded multi-source research across Pipeworx's structured data sources in one call, decomposes questions into facets, routes to tools in parallel, returns a findings packet. Clearly distinguishes from open-web search and specifies best-use cases. The differentiation from siblings like ask_pipeworx is explicit.

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

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

Explicitly says when to use: broad/multi-part questions over structured data ('compare X and Y', 'research filings + market picture'). Gives clear exclusions and alternatives: single lookup → ask_pipeworx; breaking/current news → prefer ask_pipeworx. Also mentions account tier requirements and when deep_research returns mostly empty gaps. This is exemplary usage 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false. The description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This provides useful behavioral context beyond annotations.

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

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

The description is a single paragraph but front-loads the purpose ('Find tools...'). It efficiently covers usage, examples, and output details. However, it could be broken into more structured sentences or bullet points for even quicker scanning.

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 6 parameters (with 5 aliases) and no output schema, the description explains the output format (top-N tools with schemas) and that results are ready to call. It provides examples and alias details, making it sufficient for a discovery tool. Minor gap: does not explain how the ordering or relevance is determined.

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 context by explaining that 'query' accepts natural language and lists aliases (task, q, description, search). It also gives example queries ('look up FDA drug approvals', 'analyze housing market trends') and explains the 'limit' parameter, 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 'Find tools by describing the data or task' and lists numerous example domains (SEC filings, FDA drugs, etc.). It distinguishes itself from siblings by emphasizing 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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 provided: 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and 'Call this FIRST...' This implies when to use it and when not (if you already know the tool). It does not explicitly name sibling alternatives but frames the tool's role clearly.

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 readOnlyHint and idempotentHint. The description adds value by specifying the return schema (stat_name, item_name, unit, time, data_value) and critical date-format mapping, which are beyond the 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?

The description is well-structured: purpose, required parameters with format, optional parameters, output, and usage context. Every sentence adds unique information without redundancy. It is front-loaded and efficiently packed.

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 9 parameters, no output schema, and 4 required, the description covers purpose, parameters, output fields, and workflow. It omits the limit parameter and potential error states but provides sufficient guidance for typical use. A bit more detail on optional parameters would push it to 5.

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 substantial meaning by explaining the date format per cycle (e.g., yearly='2024', quarterly='2024Q3') and providing examples. This clarifies how to construct parameter values, which is not fully evident 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 it fetches a time series from Bank of Korea ECOS with specific verb and resource. It distinguishes from sibling tools by prescribing a workflow (use after ecos_search_tables and ecos_series_items) and mentions key input components.

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 after ecos_search_tables + ecos_series_items to discover codes,' which tells the agent when to use this tool. It lacks an explicit when-not-to-use or alternative comparisons but gives clear context for proper invocation.

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 safety and idempotency. The description adds update frequency and row structure, providing useful behavioral context 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?

The description is highly concise, conveying the scope and usage in just a few sentences. Every sentence adds value, and the structure is clear.

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 aggregation tool with one parameter, the description sufficiently covers the content, return format, update schedule, and usage. No gaps given the context.

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

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

The single parameter 'limit' is fully described in the schema (100% coverage). The description does not add further parameter semantics, so a 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 explicitly lists the types of indicators and states it is a single-call aggregation of 101 series, clearly distinguishing from sibling tools like ecos_get_series which likely handle individual series. It also provides example queries.

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 usage examples for common queries, but does not mention when to avoid this tool or use sibling tools like ecos_get_series for more granular data.

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 read-only, open-world, idempotent, and non-destructive hints. The description adds context on the return format and matching behavior, which is helpful 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 concise sentences with essential information. It is front-loaded with the purpose and quickly lists key details. No unnecessary words.

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

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

Given the tool's simplicity (search directory with two parameters, no output schema), the description fully covers what the tool does, how to use it, and what it returns. Annotations cover safety and idempotency.

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

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

Schema description coverage is 100%, so the description adds no new meaning beyond what is already in the schema. It rephrases the same info (e.g., 'q is matched substring-wise' matches schema). 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 searches 'Bank of Korea ECOS statistic tables' and lists the types of economic series. It specifies the return fields (stat_code, Korean name, cycle) and distinguishes itself from ecos_get_series by saying 'Use as a directory before ecos_get_series.'

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 the usage as a directory before ecos_get_series and describes how the 'q' parameter works (substring match, blank for top-N). It provides clear context but could be more explicit about when not to use this tool vs. other 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds behavioral context: mentions most stat_codes have multiple sub-items, gives example (exchange rates with currencies), and lists returned fields (item_code, item_name, cycle, data_count, start/end period). 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 sentences that front-load the main action and purpose. No unnecessary words; every sentence provides essential information (what, why, how). 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?

Given the tool's simplicity, good annotations, and clear description of input, output, and relationship to siblings, it is largely complete. Lacks details on error handling or pagination, but these are not critical for a listing tool with openWorldHint.

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 described. Description adds value by mentioning stat_code comes from ecos_search_tables and provides an example value ('731Y001'). However, it does not add meaning beyond the schema for the limit parameter (default/max already in schema). Baseline 3 with minor extra 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?

Clearly states it lists sub-items within a Bank of Korea ECOS statistic table, using specific verb 'List' and resource 'items (sub-series) within a Bank of Korea ECOS statistic table'. Distinguishes from siblings like ecos_get_series and ecos_search_tables by explaining its role in discovering item codes needed later.

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 instructs to pass stat_code from ecos_search_tables and notes the purpose is to discover item codes for ecos_get_series. Provides clear context on when to use (to get sub-items) and relationship to other tools, though it doesn't explicitly state 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?

Beyond the readOnly/idempotent annotations, the description reveals parallel fan-out, GDELT→GNews fallback, sources_used/sources_failed semantics, empty-section meaning, name resolution, and resolved:false+notes for private companies. This is far more transparency than the annotations alone 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 long but front-loaded with the core purpose and usage preference, then enumerates sources, return fields, and edge cases in an organized flow. A few examples are redundant with the schema's type/value descriptions, preventing a 5.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so by listing every major section, the source behind it, fallback behavior, and edge-case responses. The level of detail is sufficient for an agent to call and interpret the result correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds examples, zero-padded CIK formatting, SEC EDGAR name resolution, and explicit interchangeability of type values. It reinforces the schema rather than replacing it, so 4 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 immediately frames the tool as a 'full cross-source profile of a US public company in ONE parallel call' and anchors it with concrete user phrasings. It is specific about the resource, scope, and source breadth, and explicitly contrasts with chained single-source 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?

It explicitly says to prefer this tool over chaining single-pack SEC/XBRL/news lookups for holistic profile requests, and gives accepted input shapes. It does not explicitly contrast with sibling tools like deep_research or compare_entities, which limits it slightly below a full 5.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds relevant context about use cases for stale/sensitive data, but no additional behavioral details beyond what annotations imply.

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 with front-loaded primary action, 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?

Fully adequate for a simple deletion tool with one parameter and no output schema; covers purpose, usage, and related tools.

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 parameter 'key' with 100% description coverage. Description adds no extra semantics beyond the schema's own description, 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?

Clearly states the action (delete) and resource (memory by key), with explicit distinction from siblings 'remember' and 'recall'.

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 when-to-use conditions (stale context, task done, clear sensitive data) and names related tools for 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, openWorldHint, idempotentHint, and non-destructive. The description adds context by explaining the process (fetches page, extracts title/description/key links) and that output is a single text blob. This aligns with annotations and adds useful behavioral detail, but does not go significantly beyond 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 of three sentences, front-loaded with the main action. Every sentence adds value, and there is no redundant or filler content. It efficiently communicates purpose, process, and use cases.

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 only two parameters, no output schema, and rich annotations, the description covers the essential behavioral aspects: what it does, how it works, and what the output looks like. It also provides practical use cases, making it complete for an agent to understand and invoke correctly.

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

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

Schema coverage is 100%, with both parameters (url, max_links) described in the schema. The description does not add substantial meaning beyond the schema; it implies the URL is used for fetching but doesn't elaborate on max_links. Baseline score of 3 is appropriate as the schema already handles parameter semantics.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the output format and target users. It distinguishes itself from siblings by its unique function of creating an AI crawler index file, which is not duplicated by any sibling tool.

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 lists use cases: getting a client's site indexed, drafting for own project, auditing competitors. While it doesn't explicitly mention when not to use, the use cases are clearly stated and sufficient for an agent to decide when to invoke 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 indicate readOnlyHint and non-destructive nature. Description adds value by specifying that it returns active subscriptions by default and mentions the optional parameter for inactive ones. 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?

Two concise sentences, front-loaded with the purpose and return fields, 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?

With no output schema, the description lists key return fields. It lacks pagination details but is sufficient for a simple list tool. Given the context signals, it's nearly 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 single parameter is described in the schema with 100% coverage. The description adds context by clarifying 'include_inactive' and its effect (include cancelled subscriptions).

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 ('List') and resource ('subscriptions'), and lists return fields (id, type, etc.). It effectively distinguishes from siblings like subscribe and unsubscribe.

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: 'review what you're monitoring before adding more or to find an id to cancel.' Provides clear usage 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?

Beyond annotations (all false), the description discloses key behaviors: filing without an account returns a claim_token, rate-limited to 5 per identifier per day, free and doesn't count against quota, and team reads digests daily. It also explains the claim_token workflow for reading resolution status. This is rich context beyond what annotations provide and there is 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 dense but well-structured, front-loaded with a clear summary and then covering usage, exclusions, formatting, and policy. Every sentence contributes value, though a few phrases (e.g., 'Not sure? Pipeworx tool names are the ones this connection lists') could be trimmed without losing meaning. Still, it remains concise for the complexity it covers.

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 thoroughly explains the return mechanism (claim_token), the resolution workflow, rate limits, scope boundaries, and formatting expectations. It leaves little ambiguity about when and how to use the tool, making it complete for a feedback submission 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 detailed descriptions for all four parameters. The description adds extra semantics, especially for claim_token: 'pass the pwfb_… token that filing returned, with no other arguments' and explains that filing returns this token. This clarifies the usage pattern beyond 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 clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies feedback types (bug, feature/data_gap, praise) and explicitly distinguishes from siblings by noting it is ONLY for tools served by this Pipeworx connection and not for other MCP servers.

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 when-to-use guidance (bug, feature/data_gap, praise) and when-not-to-use guidance (if the tool is from a different MCP server, file with that server instead). It also gives formatting advice (describe in terms of Pipeworx tools/packs, don't paste the end-user's prompt), making it clear how to use the tool effectively.

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 significant context: data source (CF analytics-engine), no PII, composition (pack, tool, count), and caching duration (5min-1h). This goes well 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 three sentences, front-loaded with the primary output. It uses bullet-style numbering for use cases. Every sentence adds unique value, with no fluff or repetition.

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

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

Given one optional parameter and no output schema, the description covers all needed details: return type (top tools, top packs, call volume), window options, use cases, caching, and ethical note (no PII). Completeness is excellent for 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?

Schema covers the single parameter 'window' with enum values and description. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enriches understanding beyond the enum labels.

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 'top tools, top packs, and total call volume over a recent window'. It specifies the resource (trending data) and the action (returns). While it doesn't explicitly differentiate from siblings like discover_tools, the purpose is direct and 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 lists three specific use cases (discovering hot data sources, confirming canonical tools, checking alignment) and mentions caching behavior. It provides good context for when to use, though it doesn't give explicit alternatives 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?

The description adds extensive context beyond annotations: similarity threshold (Jaccard ≥0.30), partition filter (placeholder slugs >20% yield null), fill check with realizable_edge_pp, and mentions that deviations >3pp trigger signals. No contradiction with annotations (readOnlyHint, etc.).

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

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

The description is dense and well-structured (modes, semantic anchor, partition filter, response, fill check), but slightly verbose due to detailed examples. Front-loaded with main purpose, but some 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?

Despite no output schema, the description thoroughly explains the response structure (opportunities[], partition_check) and covers edge cases (similarity, placeholders, fill check). References to sibling tool polymarket_fill_risk show completeness.

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 event and topic. The tool description adds value by explaining URL acceptance for event and providing seed question examples for topic, as well as behavioral differentiation between the two 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 detects arbitrage via monotonicity violations and partition-sum checks, and distinguishes three modes: trending scan (no args), event slug, and cross-event topic scan. The verb 'find' and resource 'arbitrage opportunities on Polymarket' are specific, and the differentiation from siblings like polymarket_fill_risk is implied.

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: 'Call with NO args for trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also warns when not to trade based on fill check results and mentions polymarket_fill_risk for custom sizing, providing clear 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 declare readOnlyHint, idempotentHint, etc. The description adds extensive behavioral context: model details (crypto_price, news_momentum, structural_arbitrage), caching (1h KV), fed candidates exclusion, and diagnostic output. 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 long but well-organized with clear segmentation (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.), front-loaded purpose, and no wasted words. Every sentence adds 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 9 parameters, nested output, and no output schema, the description fully explains output structure (by_segment, fed_candidates, _diagnostics), knobs, and caching. It is complete for an agent to use effectively.

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 significant value beyond the schema by explaining parameter usage (e.g., slippage_pp notes Polymarket fees, min_partition_leg_kelly explains basket trade behavior).

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price', which is a specific verb+resource. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx edge 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?

It explicitly says 'Built for "what should I bet on today"' and explains tradeable-edge knobs and their purposes. However, it does not explicitly compare to sibling tools like polymarket_arbitrage, missing some guidance on when to use alternatives.

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

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

The description extensively discloses behavioral traits: response structure (tracked, expired, snapshot_dates), decay computation on |edge_pp_net|, sign conventions (negative=SELL YES), and snapshot gaps. Annotations already indicate readOnly and idempotent, and the description adds rich context 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?

The description is fairly long but well-organized: first sentence states purpose, then detailed response fields, then limitations. It could be more concise, but each sentence adds value given the tool's complexity.

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

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

Despite no output schema, the description thoroughly explains the three response arrays, including edge_pp_net time-series, trend, decay, expired opportunities with lifespan, and snapshot gaps. Limitations and data source are also covered. Complete for a telemetry 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%, but the description adds defaults (days=14, window='1wk'), clamping for days (2-30), and explains the meaning of 'window' as a snapshot family. This adds meaningful context beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: answering 'how long has this edge existed and is it shrinking?' It distinguishes itself from the raw edge tool (polymarket_edges) by focusing on persistence and decay telemetry. The title 'Edge Tracker' aligns with this.

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 when to use the tool (for aging edges vs. fresh ones) and includes limitations (60-day TTL, not intraday). It implicitly distinguishes from sibling 'polymarket_edges' by focusing on time-series rather than a single snapshot.

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, openWorld, idempotent, and non-destructive. The description adds behavioral context: it walks the order book ladder, calculates slippage, returns verdicts, and identifies thin legs and forced directional risk. This goes beyond annotations, though more detail on idempotency or side effects could improve transparency.

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

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

The description is well-structured with clear sections for single-market and basket modes, uses bold for key terms, and every sentence conveys essential information with no redundancy. It is dense but not verbose, earning its length.

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 fully enumerates return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), explains constraints (requires one of market or event), and covers risks (thin_legs, forced_directional_risk). It is complete for understanding the tool's behavior and results.

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

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

Schema coverage is 100% with each parameter described. The description adds further meaning: explains the auto side default for basket mode, interprets size_usd for basket as 'settlement notional', and notes clamping range (10–1,000,000). This adds value beyond the schema's basic descriptions.

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

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

The description explicitly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishes between single-market and basket modes, and lists return fields. It also directs usage before specific sibling tools like polymarket_arbitrage and polymarket_edges, ensuring clear differentiation.

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 concrete guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (theoretical overround not capturable, partial basket fills cause directional risk) and details when to choose single-market vs basket mode via required parameters.

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?

This is a model of transparency. It discloses fee modeling limitations ('does not model Kalshi's fee schedule'), explains compatibility_codes semantics, details skipped classification behaviors, and clarifies the meaning of null temporal_alignment. It augments the readOnly/openWorld/idempotent annotations with critical caveats about gross vs net spreads and the fallibility of matching.

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

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

The description is long but well-structured with explicit section headers (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the core purpose and then systematically details safety and edge cases. While verbose, every sentence contributes necessary context for safe and correct invocation of this complex tool. The length is justified by 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?

For a tool with no output schema but high complexity, the description is remarkably complete. It covers response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, compatibility_codes), all possible codes, skip counts (skipped_cross_type/subtype), fee disclosure, and temporal alignment handling. An agent has everything needed to interpret results correctly without additional lookup.

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

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

The schema already documents all three parameters (100% coverage), so baseline is 3. The description adds semantic value: it explains that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and provides concrete examples ('fed' → 'KXFED-26OCT', 'fed-decision-in-june-825'). This goes beyond schema descriptions to clarify the interaction between 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 opens with a precise definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes itself from siblings like polymarket_arbitrage by specifying the cross-venue nature and the two modes (topic shortcuts and explicit tickers). The verb is specific ('spread'), and the resource is unambiguous.

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

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

The description explains both modes explicitly and when each is appropriate: use topic for pre-mapped macros, use explicit tickers for custom pairings. It also warns that 'pre-mapped ≠ tradeable' and that most topics return compatibility_warning, guiding the agent to scope expectations. It does not explicitly name alternatives among siblings, but the operational 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 already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context: the dual behavior when key is omitted (list all keys), scoping information (anonymous IP, BYO key hash, account ID), and pairing with 'remember' and 'forget'. This enriches the agent's understanding 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 three sentences, front-loaded with the core action and dual behavior. It efficiently covers purpose, usage, and scoping without redundancy. While concise, it could be slightly tighter by merging the second and third sentences, but overall it is 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?

Given the tool's simplicity (one optional parameter, no output schema, and safety annotations), the description covers all necessary aspects: dual modes, scoping, pairing with siblings. It leaves no gaps in understanding for an agent.

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

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

The input schema has 100% coverage with a description for the 'key' parameter: 'Memory key to retrieve (omit to list all keys)'. The description adds semantic meaning by giving examples of what keys represent (e.g., 'user's target ticker, an address, prior research notes'), which helps the agent understand the kind of data it can retrieve.

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 explicitly states the tool's purpose: 'Retrieve a value previously saved via remember, or list all saved keys.' It uses the verb 'retrieve' and clearly distinguishes between the two behaviors based on whether the key argument is provided. This sets it apart from siblings like 'remember' and 'forget'.

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 usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions scoping and pairs with 'remember' and 'forget' for a complete workflow. No explicit exclusions or alternatives are given, but the guidance is sufficient for the tool's simplicity.

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 readOnlyHint, idempotentHint, etc. The description adds that setting mark_read:true flags events as read, affecting subsequent calls. This adds context beyond annotations, but no mention of rate limits or other behavioral details.

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 of four sentences that front-loads the main purpose. Every sentence adds useful information with no redundancy or 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 simplicity of the tool (read-only listing with filters) and comprehensive schema and annotations, the description is complete. It explains returned fields, filtering, the mark_read behavior, and provides an alternative access method.

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 providing an example for 'type' (e.g., 'sec_8k') and explaining the effect of 'mark_read' on future calls. This goes beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying verb and resource. It does not explicitly distinguish from siblings like 'list_subscriptions' or 'recent_changes', but the specific resource and action are well-defined.

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 indicates that polling works fine and provides an alternative endpoint (GET registry.pipeworx.io/alerts.json) for scripts and dashboards. It mentions filtering options but lacks explicit when-not-to-use guidance relative to 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 readOnly, idempotent, and non-destructive behavior. The description adds significant context: parallel fan-out to multiple sources, fallback logic (GDELT→GNews), soft-fail for USPTO, and return structure including grouped changes, total count, and citation URIs.

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, uses bullet-style prose for sources, and each sentence provides essential information without redundancy. It efficiently conveys complex multi-source behavior in a compact form.

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 return format (structured changes grouped by source, total_changes count, pipeworx:// URIs), covers all edge cases (fallbacks, soft-fail), and addresses window format variants. It is complete for an agent to understand and invoke 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?

Input schema has 100% coverage with descriptions, providing baseline 3. The description adds value by explaining the `since` parameter formats (ISO date, relative shorthand) and usage examples ('30d', '1m'), and clarifying `type` is limited to 'company'.

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 specifies 'change feed for a company in the last N days/weeks/months' with concrete example queries, lists data sources (SEC, GDELT/GNews, USPTO), and distinguishes itself from the sibling tool 'entity_profile'.

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 usage context with example phrases like 'What's new with X', recommends typical monitoring windows, and clearly states when to use the sibling 'entity_profile' instead ('Use entity_profile instead when you want the static profile').

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

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

Discloses key behavioral details beyond annotations: key-value storage, scoping by identifier, persistence (authenticated persistent, anonymous 24 hours). No contradiction with annotations (idempotentHint=true matches storage behavior).

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

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

Front-loaded with purpose, then usage, examples, behavior, companion tools. Every sentence adds value without redundancy. Length is appropriate for detail provided.

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 adequately covers storage behavior, persistence, scoping, and companion tools. Agent has all necessary context for correct 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 clear descriptions for key and value. Description adds no new parameter semantics but reinforces intended usage patterns. 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?

Description clearly states the tool's purpose as saving data for reuse across conversations/sessions, with specific examples (ticker, address, preference) and distinct verb-resource pairing. It distinguishes from siblings like recall and forget.

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 ('discover something worth carrying forward') and mentions companion tools (recall, forget). Also covers behavior differences for authenticated vs anonymous sessions.

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

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

Annotations already declare read-only, open-world, and idempotent hints, and the description adds substantial behavioral context beyond those: it cascades through multiple lookup endpoints, returns `figi_candidates` when ambiguous, states unresolved identifiers explicitly rather than omitting them, and degrades gracefully when GLEIF/OpenFIGI are unavailable. 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 front-loaded with usage intent and query examples, and nearly every sentence adds value. It is dense and long, with a very large parenthetical block, so it is not maximally concise, but the complexity of the tool justifies most of the 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?

Despite having no output schema, the description explains key return behaviors, including source labelling, explicit unresolved identifiers, and ambiguity handling via `figi_candidates`. It covers supported types, accepted value formats, fallback behavior, and caveats, so an agent has enough to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: detailed value examples per type, the difference between ticker/CIK/ISIN/name inputs, and a concrete warning not to pass full noun phrases for bonds. This materially reduces the chance of malformed invocations.

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

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

The description names a specific verb and resource: resolving user-spoken names into canonical/official identifiers, illustrated with concrete query examples. It clearly positions the tool relative to siblings by noting these IDs are what other tools require as input, and it enumerates supported entity types (company, drug) rather than remaining generic.

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

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

It gives an explicit trigger condition: 'Use FIRST whenever you have a name but need an ID,' plus query-phrase examples and supported input forms. It does not explicitly name sibling alternatives to avoid or provide when-not-to-use guidance, so it stops short of a full 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?

Description adds behavioral details beyond annotations: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. This complements the readOnly, idempotent, and openWorld annotations well.

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 primary sentences with an example, front-loaded with main action. Every sentence adds value; no fluff. 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?

Despite no output schema, description clearly states the return type (ranked list with score, confidence, signal density). The tool's moderate complexity is fully covered, and the description leaves no major 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%, but description adds value: it explains that the first entity is treated as subject for narrative, clarifies that models default to workers-ai and _apiKey is only needed for anthropic. This goes beyond the schema descriptions.

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

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

Description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, and returns a ranked list. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

Explicitly states use case for competitive AI-marketing audits with example ('does Claude know about us?'). While it doesn't explicitly exclude single-entity use, the implication is clear due to sibling 'ai_visibility_check' being the single-entity counterpart.

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 behavioral details: partial failures from bundlephobia timeout (5-30s) are handled gracefully, reported in sources_failed. 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 paragraph but packed with essential details; it could be broken into bullet points for readability, but it remains efficient and front-loaded.

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

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

No output schema, but the description thoroughly enumerates return fields and structure (summary block, advisories, links, alternatives). Also covers ecosystem bounds and error handling, making it fully self-contained.

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. Description adds extra meaning: notes scoped package acceptance and default behavior for version (latest when omitted), exceeding schema 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?

The description clearly states the tool's purpose: a composite check combining deps.dev and bundlephobia to answer 'should I add this npm package'. It distinguishes from siblings by specifying NPM-only and referencing deps.dev:version for other ecosystems.

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 instructs when to use: 'whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. Also mentions fallback for PyPI/Maven/Cargo/Go, guiding the agent toward 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged)' and 'every passage carries an offset', providing transparency beyond the annotations.

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

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

The description is four sentences, each serving a distinct purpose: purpose, usage, pairing, and technical detail. It is front-loaded with 'Semantic search INSIDE a fetched record' and contains no redundant or 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?

Despite no output schema, the description explains return values (passages with offsets and similarity scores), covers technical limits (200K chars, 500-char windows), and provides usage context. All relevant aspects for a 3-parameter tool are addressed.

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 useful context: clarifies text max (200K chars), provides example queries for the 'query' parameter, and notes default and range for 'limit'. This extra info justifies a score above the baseline of 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 'Semantic search INSIDE a fetched record' provides a specific verb and resource, clearly distinguishing it from sibling tools like 'ask_pipeworx' and 'ask_pipeworx_grounded' by focusing on searching within an already-fetched record.

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

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

Explicitly states 'Use when the record is too big to cram into the prompt' and describes pairing with 'ask_pipeworx_grounded' as an alternative for grounding over relevant passages, offering 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?

Beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds critical behavioral details: delivery channel caveats (phone verification, 10/day cap, webhook auto-disable), the always-on feed, and the one-time webhook secret. 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 but front-loads the core purpose. It efficiently conveys all necessary information without fluff, though a more structured format (e.g., bullet points) could improve readability. Every sentence earns its place.

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

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

Given the complexity (3 parameters, nested objects, no output schema), the description covers return value, prerequisites, type-specific parameters, and delivery details. It is mostly complete but could mention error handling or quota limits beyond the 10/day SMS cap.

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

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

The schema has 100% description coverage, so baseline is 3. The description adds significant value by providing concrete examples for each subscription type (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02","1.01"]}') and delivery nuances, enhancing 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 the action ('Create'), the resource ('proactive monitoring subscription'), and the return value ('Returns the new subscription id'). It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing on creation.

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 the required OAuth account and limitations for anonymous/BYO users. It provides detailed context for when to use (e.g., for live-data event monitoring) but lacks explicit exclusions or comparisons to alternatives, though siblings are available.

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, destructiveHint. The description adds behavioral context (onboarding role, returns live catalog examples) without contradicting 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 somewhat long but each sentence adds value. It is front-loaded with core purpose and structured logically. Could be slightly more concise, but overall effective.

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 no required parameters and no output schema, the description is comprehensive: it explains purpose, usage, parameter behavior, return content, and relationship to other tools. 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%, but the description adds value by explaining the default behavior (no args gives full spread) and providing examples of topic values. This goes beyond the schema's brief 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 return category-bucketed example questions for onboarding, with multiple alternative phrasings. It distinguishes from siblings by positioning itself as the entry point for new users.

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

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

The description explicitly says to use this tool first when unfamiliar with Pipeworx, and explains the optional topic parameter. It does not explicitly state when not to use, but the 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 adds behavioral context beyond annotations: ownership enforcement and deactivation vs. deletion. This aligns with annotations (destructiveHint false) and provides helpful detail.

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 action, no wasted words. Each sentence earns its place.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership, side effects, and references a sibling tool (recent_alerts). Sufficiently complete.

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

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

With 100% schema description coverage, the baseline is 3. The description does not add extra parameter info beyond restating that 'id' is the subscription identifier returned by subscribe.

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 'Cancel a subscription by id' with a clear verb and resource, and it naturally distinguishes itself from siblings like 'subscribe' and 'list_subscriptions'.

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

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

It explains ownership enforcement and the deactivation effect, providing context for when to use the tool. However, it does not explicitly list alternatives or conditions when not to use it.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral detail: the two routing paths, the nuanced meanings of 'could_not_verify' vs 'unsupported', the inclusion of verification_error{stage,detail}, and the explicit warning not to treat could_not_verify as evidence. This far exceeds what annotations alone 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 dense but well structured, front-loaded with example search queries that quickly convey the tool's intent. Every sentence earns its place by explaining a distinct aspect: routing, return values, error semantics, and efficiency gains. It is appropriately sized for the tool's complexity.

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

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

Even without an output schema, the description fully explains the returned verdict types, the grounded/structured value, citation, reasoning, and the special error handling for could_not_verify. The tool is complex, and the description covers its key behaviors comprehensively, making it complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with descriptions for both 'claim' and 'tolerance_pct'. The description adds some context via 'exact percent-delta math' and 'tolerance implied by claim wording', but it does not specifically explain tolerance_pct beyond what the schema already covers. 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's purpose: natural-language claim verification against authoritative sources. It provides concrete examples and explains the two distinct verification paths (structured SEC EDGAR/XBRL for company-financial claims and a grounded pipeline for others), making it unmistakable what the tool does. This distinguishes it from the many 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 whenever the agent needs to check whether something a user said is factually correct.' It also clarifies the internal routing for different claim types and notes that it replaces 4–6 sequential calls, implying it is the go-to tool. However, it does not name any specific alternative tool for when this tool should not be used, leaving a small gap.

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