Ecos Kr

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

Annotations already indicate safe read operations (readOnlyHint, idempotentHint, openWorldHint). The description adds valuable context: it probes LLMs, returns per-model score/confidence/signals, and notes the need for a BYO key for Anthropic (cost borne by user). No annotation 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 approximately 120 words, front-loaded with the primary action, and every sentence adds value. No extraneous 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?

The description adequately covers input parameters and summarizes the output structure (per-model fields + combined view). It could mention potential error cases or rate limits, but overall it is complete for a tool with no output schema.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description reinforces the default model and mentions that _apiKey is passed through, but does not add substantial new meaning 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 uses specific verbs ('Probe', 'score') and identifies the resource (LLMs, entity visibility). It clearly distinguishes from siblings like 'scan_competitor_ai_presence' and 'deep_research' by focusing on probing multiple models for a visibility score.

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: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains when to use optional parameters (models list, _apiKey for Anthropic, context for disambiguation), but does not explicitly state when not to use the tool versus alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, establishing the tool as safe and idempotent. The description adds valuable behavioral context: it routes queries to thousands of tools, returns structured answers with stable citation URIs, and works on every tier. This goes beyond annotations but does not fully detail internal routing logic or response format.

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 relatively long but front-loaded with the key message ('PREFER OVER WEB SEARCH'). It efficiently conveys use cases, examples, and sibling distinctions without significant redundancy. A minor critique: the list of domains could be shortened, but overall it earns its length through completeness.

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

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

Given the tool's complexity (4482 tools, 1129 sources) and the lack of an output schema, the description provides essential context: it returns structured answers with citation URIs. It covers the tool's scope, route logic, and relationship to siblings. While it omits details like pagination or error handling, it is sufficient for an AI agent to understand when and how to invoke 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?

Schema description coverage is 100% (all six parameters are aliases for 'question,' with full descriptions in the schema). The description does not add additional meaning beyond what the schema already provides; it merely repeats 'Your question or request in natural language.' By the rubric, baseline 3 is appropriate when schema coverage is high and description adds no new parameter info.

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

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

The description explicitly states the tool answers questions about current/historical data across many domains, using a specific verb 'ask' and a well-defined resource (4,482 tools across 1,129 sources). It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by stating the conditions for each alternative.

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

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

The description provides explicit guidance on when to use this tool over alternatives (e.g., 'PREFER OVER WEB SEARCH'), gives conditions for stepping up to ask_pipeworx_grounded or deep_research, and includes concrete examples of appropriate questions. It also clarifies that for breaking news, ask_pipeworx already routes to live news 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?

Annotations indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds significant behavioral context: it performs an extra LLM call, uses a two-step process (routing then extraction), returns an explicit refusal with reasons when data is insufficient, and specifies the return structure. This goes well beyond the annotations.

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

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

The description is front-loaded with the main purpose, then efficiently covers behavior, return format, usage context, and cost. Every sentence serves a clear purpose, and there is no redundancy or fluff. Despite being detailed, it remains concise and well-structured.

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

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

Given the complexity of the tool (routes among many tools, performs extraction, returns structured refusals), the description covers all necessary aspects. It explains the tool's behavior, return format, usage scenarios, and cost. No output schema exists, but the description explicitly lays out the return values, making it complete.

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

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

Schema coverage is 100% with all parameters documented as aliases for the 'question' parameter. The description adds that the question is in natural language and used for routing to the right tool and filling arguments. While the schema already describes the aliases and says 'Your question in natural language', the description provides extra context about how the question is processed, which improves understanding.

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

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

The description clearly states that this tool is a hallucination-resistant answer mode for high-stakes reads. It uses specific verbs ('extracts', 'returns') and resources (tool routing, data fetching). It also distinguishes itself from the sibling tool 'ask_pipeworx' by noting the extra LLM call and the explicit refusal when data doesn't directly 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?

The description explicitly states when to use this tool: whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (e.g., financial verdicts, legal claims). It also provides guidance on when not to use it, by preferring 'ask_pipeworx' for casual lookups due to extra cost. This clearly differentiates from the sibling.

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

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

The description is extremely transparent about behavior: it resolves the market, classifies the bet, fans out to category-specific data packs, and returns structured results. It details edge cases like low-confidence resolutions, closed markets, wide spreads, and resolution-rule risk. Annotations (readOnlyHint, etc.) are consistent with the description.

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

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

The description is lengthy (multiple paragraphs) but packs substantial value. It is well-organized but could benefit from more structured formatting (e.g., bullet points or sections). Given the tool's complexity, the verbosity is justified.

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

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

With no output schema, the description fully explains return shapes: market fields, analysis block, evidence structure, resolver contract, parent event extractor, news fields, and safety logic. It covers blocking conditions and resolution-rule risk, leaving no ambiguity for the 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?

All three parameters are fully described in the input schema (coverage 100%), so the description does not add essential semantics beyond providing usage context (e.g., examples for market_input, explanation of depth options). The description reinforces but does not significantly extend the schema.

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

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

The description clearly states the tool researches a Polymarket bet by pulling relevant Pipeworx data. It specifies input types (market slug, URL, or question) and output components (evidence packet, market-vs-model comparison). It distinguishes from siblings like polymarket_edges or polymarket_arbitrage by focusing on data retrieval and classification.

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

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

The description explicitly states usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also advises inspecting match confidence before trusting analysis. However, it does not explicitly state when not to use the tool or list alternative tools for specific cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles off-calendar fiscal years, and notes that results are sorted by primary metric for easy reading. 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 effectively front-loaded with common user queries. It packs a lot of information without being verbose, though it could be slightly more structured with bullet points for different entity types.

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

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

Given the tool's complexity (two entity types, multiple data sources, comparative output), the description covers all essential aspects: what data is pulled, how sorting works, citation URIs, and efficiency gains. Without an output schema, it sufficiently describes the return format.

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 coverage is 100% with descriptions for both parameters. The description adds significant value by explaining the difference between company and drug types, providing examples (e.g., tickers, drug names), and specifying max/min items. It clarifies data sources and output behavior 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 uses specific verbs like 'compare', 'rank', and 'head to head' to define the tool's purpose. It explicitly states it performs side-by-side comparison of 2–5 companies or drugs in one call, clearly distinguishing from sibling tools like entity_profile that do single-entity lookups.

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

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

The description provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It does not explicitly list alternatives, but the context makes it clear that this tool should be used for comparisons instead of multiple sequential 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 safe, read-only, idempotent behavior. The description adds substantial behavioral context: expected response time (15-60s), return structure ('findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[]'), and guarantees ('never invented'). It also explains the internal process (decomposes into facets, parallel routing). 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 relatively long but front-loaded with the most critical information (account requirement and alternative tool). Every sentence serves a purpose: prerequisites, scope, behavior, examples, limitations, and timing. It could be slightly more concise (e.g., merging some caveats), but the structure is logical and aids comprehension for a complex tool.

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

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

Given the tool's complexity (2 parameters, no output schema, but annotations present), the description provides a holistic view. It covers the input format, expected output structure, use cases, limitations (gaps for topics not in structured catalog), alternative tools, prerequisites, and performance expectations. The agent gets a complete picture 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 description coverage is 100%, so both parameters are already documented. The description adds value by explaining the 'depth' enum values in plain terms ('quick=3, standard=5, thorough=8 (paid plans)') and clarifying that 'question' should be broad/multi-part. While schema covers basics, the description provides practical usage context that enhances understanding.

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

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

The description clearly states the tool's core purpose: 'Grounded multi-source research across Pipeworx's 1129 STRUCTURED data sources in ONE call'. It explicitly distinguishes itself from open-web search and sibling tools like ask_pipeworx, specifying its unique value: decomposition and parallel routing to 4,482 tools. The verb 'research' and resource 'structured data sources' are specific and actionable.

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 ('Best for broad/multi-part questions over structured data') and when-not-to-use ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also lists prerequisites: account required, free sign-in, and paid plan for 'thorough' depth. This leaves no ambiguity about alternatives and context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds beyond: 'Returns the 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.' 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 compact, front-loaded with the core purpose, and includes a detailed list of domains efficiently. Every sentence contributes meaningful information.

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

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

Given the parameter count (6), complete schema coverage, and no output schema, the description sufficiently explains the return value (top-N tools with schemas) and use case, making it complete 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. The description mentions the 'query' parameter's purpose but doesn't add semantics for limit or aliases beyond what the schema provides. Minimal added value.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb ('find') and resource ('tools') and distinguishes from siblings by noting it should be called first when many tools exist.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear usage context, though it lacks explicit 'when not to use' statements.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds that it returns rows with specific fields (stat_name, item_name, unit, time, data_value). No contradictions. Could elaborate on error handling but adequate.

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

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

Three sentences, no wasted words. Front-loaded with purpose, followed by parameter guidance and usage context. Optimal length for the complexity.

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

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

Covers required parameters, optional items, date formats, return fields, and usage flow. No output schema, but description compensates. Slight omission: limit parameter default/range (schema has it, but description doesn't mention max 1000).

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

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

Schema coverage is 100% (baseline 3). Description adds meaningful detail: date format per cycle with examples (yearly='2024', quarterly='2024Q3', etc.) and item code example (USD in exchange-rate table).

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 'Fetch a time series from Bank of Korea ECOS' with specific verb and resource. Distinguishes from sibling tools by recommending use after ecos_search_tables and ecos_series_items.

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 context: 'Use after ecos_search_tables + ecos_series_items to discover codes.' Provides clear when-to-use guidance. Could mention when not to use but sufficient given sibling 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 indicate read-only, open-world, idempotent, non-destructive behavior. The description adds value by stating daily updates and noting that the tool returns 101 series in one call, which goes 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 extremely concise: two sentences plus a usage example. Every sentence adds essential information without extra fluff, and the key purpose is 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?

Despite lacking an output schema, the description provides output structure (each row's fields), update frequency, and total series count. Given the simplicity of the tool (one optional param, read-only), this is fully adequate for an agent to understand what to expect.

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

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

The single parameter 'limit' is fully described in the schema (coverage 100%), so the description does not add additional semantics. It provides output structure but not parameter specifics, achieving the baseline.

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

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

The description clearly states this tool returns Bank of Korea headline economic indicators (M1/M2, exchange rates, etc.) in one call. It lists specific examples and distinguishes from sibling tools like ecos_get_series that likely handle individual 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?

Explicit usage guidance is provided: use for queries like 'what is Korea's exchange rate / interest rate right now'. However, it does not explicitly mention when not to use it or name alternative tools for more specific queries, leaving some ambiguity.

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

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

Annotations already declare readOnly, openWorld, idempotent, and not destructive. Description adds that search uses substring matching and returns specific fields (stat_code, Korean name, cycle), which aligns with and complements 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?

Three sentences with no filler. Front-loaded with key information: what it does, what it returns, how to use it. Every sentence adds value.

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

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

Given simple parameters and no output schema, description fully specifies behavior and return format. Context includes sibling tools and workflow guidance toward ecos_get_series, making it complete for a directory-like tool.

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

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

Schema covers 100% of parameters with descriptions. Description enhances by explaining substring matching for q and browsing behavior for empty q, adding meaning beyond the schema definitions.

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

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

Description states 'Search Bank of Korea ECOS statistic tables' and lists categories of economic series. It specifies returns (stat_code, Korean name, cycle) and distinguishes from siblings like ecos_get_series, making the purpose clear and specific.

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 as a directory before ecos_get_series,' guiding when to use this tool. Also explains that q is substring-matched against Korean names and blank returns top-N, giving clear usage contexts.

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 as true and destructiveHint as false. The description does not contradict these; it adds behavioral details about the return fields (item_code, item_name, cycle, data_count, start/end period). No hidden side effects are suggested.

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

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

The description is three sentences, each providing essential information. It front-loads the purpose, follows with the common case, and ends with the typical usage flow. No redundant or unnecessary sentences.

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

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

Despite lacking an output schema, the description details the return fields and explains the tool's role in the ECOS tool ecosystem. It connects to ecos_search_tables and ecos_get_series, making it complete for an agent to understand when and how to use it.

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

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

Schema coverage is 100% with both parameters described. The description adds value by explaining the stat_code parameter's role (from ecos_search_tables) and the typical multiplicity of items (e.g., exchange rate example). The limit parameter is not elaborated but its default/max is already in the schema.

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

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

The description clearly states the tool lists items within a Bank of Korea ECOS statistic table. It specifies the verb 'list', the resource 'sub-series', and provides context with an example (exchange rate table). It distinguishes from siblings like ecos_search_tables and 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 explicitly tells the agent to pass the stat_code from ecos_search_tables and states the purpose is to discover item codes needed by ecos_get_series. This provides clear usage context. While it doesn't explicitly mention when not to use it, the instructions are sufficient for an agent.

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 substantial behavioral context: it is a parallel call, fans across multiple sources, returns specific fields, and notes a potential soft-failure for patents (USPTO PatentsView API sunset May 2025). 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 with examples first, then purpose, usage guidance, and detailed returns. It is slightly long but every sentence adds value. A minor reduction for verbosity in listing return fields, but overall efficient.

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

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

Given the tool's complexity and lack of output schema, the description comprehensively explains return fields (CIK, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It covers both parameters and the tool's behavior sufficiently for an agent to 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 description coverage is 100%, and the description adds meaning beyond the schema. It explains that 'type' currently only supports 'company' and 'value' can be a ticker or zero-padded CIK, explicitly noting that names are not supported. This helps the agent understand parameter constraints and usage.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company' and lists specific use cases like 'Tell me about X' and 'company profile for Microsoft'. It distinguishes itself from siblings by advising to 'ALWAYS PREFER over chaining single-pack lookups when holistic view needed'.

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

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

Explicit when-to-use: 'when a user asks for a holistic view'. Also clarifies when not to use: 'names not supported (use resolve_entity first if you only have a name)'. This provides clear guidance on 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 indicate destructiveHint=true and idempotentHint=true, so the description's 'Delete' aligns. It adds context about clearing sensitive data but does not cover behavior for missing keys or error handling. With annotations covering the safety profile, a 3 is appropriate.

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

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

Two sentences, zero waste. The first sentence defines the action, the second provides usage context. Every phrase 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?

Tool is simple with one parameter and no output schema. Description covers purpose and usage conditions. Minor gap: does not mention return value or behavior on missing key, but acceptable given simplicity.

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

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

Schema coverage is 100% and the description's 'by key' adds no meaning beyond the schema's 'Memory key to delete.' Baseline of 3 is correct when schema already handles parameter documentation.

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

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

Description explicitly states 'Delete a previously stored memory by key,' using a specific verb and resource. It clearly distinguishes from sibling tools like 'remember' and 'recall' by indicating deletion.

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

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

Description provides explicit when-to-use conditions (stale context, task done, clear sensitive data) and mentions pairing with sibling tools. It lacks explicit when-not-to-use guidance 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?

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds that it fetches and extracts content, but could clarify error handling for unreachable URLs.

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

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

The description is concise with three sentences, front-loading the main purpose, and every sentence adds value without redundancy.

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

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

For a simple tool with two parameters and no output schema, the description adequately explains input, process, output, and use cases.

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

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

Schema covers both parameters fully (100% coverage). Description does not add extra detail beyond implying url is required and max_links is optional, so baseline score applies.

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

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

The description uses a specific verb 'Generate' and resource 'llms.txt file', and clearly distinguishes from any sibling tools by specifying the output format and use cases.

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 explicit use cases (client site, own project, competitor audit), but does not mention when not to use it or prerequisites like URL accessibility.

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

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

Annotations already declare readOnlyHint and idempotentHint; description adds return fields, but no further behavioral details needed.

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

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

Two sentences, front-loaded with purpose, no waste.

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

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

Simple read-only list tool with annotations and one optional param; description mentions return fields, sufficient 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 covers the sole parameter fully (100% coverage), description adds no additional meaning beyond schema.

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

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

States 'List the caller's active subscriptions' with specific verb and resource, distinguishes from sibling tools '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?

Explicit guidance to use when reviewing monitoring before adding more or finding an id to cancel, providing clear when-to-use context.

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

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

Annotations are present but minimal; the description adds substantial behavioral details: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota. 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 a single paragraph but well-organized with clear instructions. It is not overly verbose and each sentence contributes useful information. Slight improvement could be more bullet points, but it is 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?

Given no output schema, the description doesn't detail return values, which is acceptable for a feedback tool. It covers usage, constraints, examples, and caveats comprehensively. The context is complete for the agent to use 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 value by explaining the enum values in plain language and providing guidance on how to write the message. This clarifies intent beyond the schema's parameter 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: sending feedback to the Pipeworx team about bugs, features, data gaps, or praise. It uses specific verbs and resources, and distinguishes itself from sibling tools by detailing the exact types of feedback.

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 scenarios (bug, feature/data_gap, praise) and what not to do (don't paste end-user prompt). It also includes rate limits and quota information. However, it does not explicitly compare with sibling tools, though its unique purpose makes alternatives 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 provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: self-aggregating signal, derived from CF analytics-engine, no PII, cached 5min-1h. No contradictions.

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

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

Two paragraphs, front-loaded with main output, then use cases, then technical details. Every sentence is informative and non-redundant. 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 (1 optional param, no output schema), the description is complete: explains data source, caching policy, use cases, and data format. Nothing essential is missing.

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

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

Only one parameter 'window' with enum, and schema description covers it (100% coverage). The description adds context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds 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 verb+resource: 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' It differentiates from sibling tools like 'ask_pipeworx' and 'discover_tools' by focusing on trending and call volume, making the purpose unambiguous.

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

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

Three explicit use cases are listed (discovering hot data sources, confirming canonical tool, checking alignment). While it doesn't explicitly state when not to use, the context is clear. Could mention alternatives for detailed search, but still strong 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?

Adds rich behavioral details beyond annotations: required parameters, semantic anchor (Jaccard similarity), partition filter, fill check against live CLOB depth, and response structure. No contradiction with annotations (readOnlyHint ensures no side effects).

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

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

Well-structured with a front-loaded requirement, but somewhat verbose. Each sentence adds value, but could be more concise while retaining clarity. Minor improvement possible.

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?

Extremely complete given the tool's complexity and lack of output schema. Explains response fields, edge cases (placeholders, fill check), and limitations. No gaps remain for an AI agent to understand proper 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?

Despite 100% schema coverage, the description adds significant semantic value: explains the difference between event and topic, provides example values, and notes that call with no args fails. The description goes beyond the schema to clarify usage.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, with two distinct modes (event and topic). It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection.

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

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

Explicitly warns that calling with no args fails, explains when to use event vs topic, and mentions an alternative tool (polymarket_fill_risk) for custom sizing. Provides clear context about mode selection.

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

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

Annotations declare read-only, open-world, idempotent, non-destructive. The description goes far beyond, detailing three model families with methodologies, field definitions (edge_pp_net, kelly_fraction), tradeable-edge knobs, caching, 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 sections in caps and a front-loaded purpose. Every sentence adds value, though it could be slightly more concise (e.g., using bullet points). Still, it earns its length for an AI agent.

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

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

Given 9 parameters, no output schema, and complex logic, the description covers everything: model families, response structure, filtering knobs, diagnostics, caching, and Fed bets disclaimer. It is remarkably complete.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds context by explaining how knobs like min_liquidity and max_spread_pp filter opportunities, elevating 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 clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It is built for daily betting discovery, distinguishing it from sibling tools like polymarket_edge_tracker or polymarket_arbitrage.

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

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

The description implies use for daily betting opportunities but does not explicitly contrast with siblings or state when not to use it. The context is clear but lacks exclusions or alternative recommendations.

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

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

Annotations (readOnlyHint, idempotentHint) already indicate safe read-only operation. Description adds useful behavioral details: history bound by 60-day TTL, decay from daily closes not intraday, snapshot gaps due to cache-miss. Adds value beyond annotations.

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

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

Front-loaded with purpose but includes many details in one dense paragraph. Could be broken into sections for readability, but every sentence earns its place by adding essential information.

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

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

No output schema, but description fully details the response structure (tracked[], expired[], snapshot_dates[]) with explanations of each field. Compensates completely for lack of output schema.

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

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

Schema coverage is 100%. Description explains parameters with defaults, constraints (max 30) and purpose (lookback, snapshot family), adding significant meaning beyond schema field 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 it provides edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?' This specific verb+resource distinguishes it from sibling tool polymarket_edges which likely gives current edges.

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 context on when to use: differentiating between new and old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'). Does not explicitly state when not to use or name alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds significant behavioral context: it walks the order ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about risks like forced directional risk and thin legs. This goes well beyond the annotation hints.

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 quite long (~500 words) but well-structured, starting with overall purpose, then mode-specific details, then usage guidance. It contains all necessary return field descriptions (since no output schema). A few sentences are dense, but overall the length is justified by the tool's complexity.

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

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

Given the tool's complexity (two modes, multiple return fields, risk implications), the description covers everything comprehensively. It explains each mode's inputs, outputs, and risks, and ties usage to sibling tools. The lack of output schema is compensated by detailed field descriptions in the tool text.

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 each parameter already has a basic description. However, the tool description adds meaningful nuance: explains the two modes (market vs event), default auto logic for side in basket mode, and interpretation of size_usd (settlement notional for basket). This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by explicitly stating to use this tool before those, and provides specific mode explanations (single-market vs basket).

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (partial fills create directional risk, theoretical overround not capturable on thin books), effectively telling the agent when and why to use this tool over 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, the description details behavioral nuances: two modes, response structure, safety fields (compatibility_warning, temporal_alignment, skipped_cross counters), and explains when spreads are meaningless. It discloses that real spreads are rare despite the shortcut list.

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 thorough but somewhat verbose. It is front-loaded with the core concept and structured with headings-like paragraphs for modes, response, and safety fields. A slightly more concise presentation could improve readability without losing 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 no output schema, the description comprehensively covers the response fields (spread, compatibility_warning, temporal_alignment, skipped counters) and edge cases. It leaves no major gaps given the tool's complexity.

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

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

Schema coverage is 100%, and the description adds significant context: it explains the topic mode with a list of shortcuts, clarifies that explicit tickers override the topic side, and provides examples. This goes well beyond the schema's property 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 computes cross-venue spread between Kalshi and Polymarket, describes two modes (topic shortcuts and explicit tickers), and explains the response. It differentiates from sibling tools like polymarket_arbitrage by focusing on cross-venue spreads.

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 on when to use each mode, explains safety fields like compatibility_warning, and warns that pre-mapped topics often yield warnings. It implicitly distinguishes from intra-venue tools by focusing on cross-venue comparison.

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, destructiveHint. Description adds behavioral context like scoping to identifier and listing all keys, which is valuable but not critical beyond annotations.

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

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

Two sentences, front-loaded with core action, no wasted words. Perfectly concise for the tool's simplicity.

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

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

For a simple read-only tool with one optional parameter, the description fully covers purpose, usage, and behavioral context. No output schema is needed.

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

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

One parameter (key) with 100% schema coverage. Description adds meaning by explaining it's optional and listing all keys if omitted, beyond the schema's minimal 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?

Description clearly states the tool retrieves values saved via remember or lists all keys when no key is provided. It distinguishes itself from sibling tools 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?

Explicitly states when to use (look up stored context) and mentions pairing with remember/forget. Notes scoping to user identifier, providing clear guidance.

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

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

The description contradicts annotations: it describes mark_read as a state-modifying feature (flagging events read), while annotations set readOnlyHint, idempotentHint, and destructiveHint=false. This is an annotation 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 concise (4 sentences), front-loaded with the purpose, and each sentence adds necessary information without redundancy.

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

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

The description covers return fields (source, citation_uri, raw payload) and key behaviors (filtering, mark_read, poll compatibility). It lacks details on response shape and limit parameter behavior, but given openWorldHint and no output schema, it is largely sufficient.

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 examples (e.g., 'sec_8k') and explaining the effect of mark_read, going 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 verb 'Pull' and the resource 'fired events from your subscription feed'. It distinguishes from sibling tools like list_subscriptions and recent_changes by focusing on alerts.

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

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

The description explains how to filter by type and since, and how to use mark_read to track read status. It also mentions an alternative access method (GET endpoint). However, it does not explicitly state when not to use this tool versus 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 provide readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral context: fanning out to multiple sources, GDELT→GNews fallback behavior, USPTO soft-fail, and return structure (changes[] grouped by source, total_changes, citation URIs). 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 a single efficient paragraph that packs essential information without wasted words. It could be slightly more structured (e.g., bullet points for sources), but it remains clear and front-loaded with key 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?

Despite no output schema, the description explains the return shape (changes[] grouped by source, total_changes count, citation URIs) and covers all sources and fallback behaviors. For a 3-parameter tool with clear purpose, this provides complete context for an AI agent to 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 has 100% description coverage for all 3 parameters. The description adds value by explaining `since` accepts ISO date or relative shorthand with examples, `value` can be ticker or CIK, and `type` is limited to 'company'. This provides concrete usage 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?

Description clearly states the tool provides a change feed for a company, with specific examples like 'What's new with X' and lists fan-out sources (SEC EDGAR, GDELT→GNews, USPTO). It distinguishes from the sibling tool `entity_profile` by noting when to use the latter for static profiles.

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

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

Description explicitly tells when to use the tool (for change feed queries) and recommends using `entity_profile` instead for static profiles. It also provides guidance on the `since` parameter ('Use "30d" or "1m" for typical monitoring'). However, it does not explicitly state when not to use it beyond the alternative tool mentioned.

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 idempotentHint=true and non-destructive. The description adds behavioral context: scoped by agent identifier, persistent for authenticated users, 24-hour memory for anonymous. 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 concise (3 sentences) but packs essential info: purpose, usage, behavior, and pairing with other tools. Front-loaded with the main action, then usage, then details.

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

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

For a simple key-value storage tool, the description covers all needed aspects: purpose, when to use, persistence, scoping, and related tools. No output schema is needed as return values are implicit.

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

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

Schema has 100% coverage with clear descriptions for key and value. The description adds example key names (subject_property, target_ticker) which helps the agent use the parameters correctly, only slightly surpassing the schema alone.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' and provides specific examples (resolved ticker, target address, etc.), distinguishing it 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 tells when to use: 'when you discover something worth carrying forward' and pairs with recall/forget for retrieval/deletion. Also explains scoping and persistence (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 readOnlyHint, idempotentHint, etc., lowering the bar. The description adds value by disclosing that it cascades through multiple internal endpoints and replaces 2-3 manual lookups, and specifics what each type returns (ticker, CIK, company_name; RxCUI, ingredient, brand). 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?

Concise and well-structured. Front-loaded with example queries. Uses bullet points for supported types. No unnecessary sentences. Five sentences covering purpose, usage, returns, and internal 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?

Given the tool's simplicity (2 params, no output schema), the description is complete. It covers all needed info: what each type returns, inputs accepted, and internal behavior. No gaps for typical use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant detail: explains subtypes, what they return, acceptable input formats (ticker, CIK, name; brand/generic), and mentions auto-disambiguation. Exceeds baseline.

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

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

The description clearly and specifically states the tool resolves names to canonical identifiers, with concrete examples like ticker, CIK, RxCUI. It distinguishes from sibling tools by explicitly saying 'Use FIRST whenever you have a name but need an ID.'

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 guidance: 'Use FIRST whenever you have a name but need an ID.' Lists supported types and their inputs. 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?

Annotations provide safety profile (readOnly, idempotent, not destructive). Description adds internal behavior: probes each entity with ai_visibility_check, returns ranked list with score/confidence/signal density. No contradiction.

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

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

Three sentences, front-loaded main action, then method and use case. No fluff, every sentence adds value.

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

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

No output schema, but description explains return format. Covers all parameters and use case. Lacks error handling or limitations, but adequate for comparison 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 100%. Description adds context beyond schema: first entity is subject, context disambiguates, models list supported values. Adds marginal but useful 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?

Clearly states action: 'Compare AI visibility across multiple entities side-by-side.' Specifies verb (compare, scan, probe) and resource (AI visibility). Distinguishes from sibling 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?

Describes use case: competitive AI-marketing audits with example question. Implicitly when not to use: single entity check should use ai_visibility_check. Mentions first entity is narrative subject. Lacks explicit exclusions.

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

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

Goes well beyond annotations by detailing the composite fan-out to deps.dev and bundlephobia, the return fields summary, partial failure handling, and the potential time delay. 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?

Well-structured and front-loaded with the composite nature and key services. Every sentence adds value, though slightly verbose. Could be condensed but remains clear and efficient.

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

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

No output schema, so description fully covers return values (summary block, advisories, links, alternatives) and partial failure behavior. Addresses the complex composite nature and potential delays comprehensively.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds context that scoped packages are accepted and version defaults to latest, but this is largely redundant. Baseline 3 is appropriate.

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

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

The description clearly states it is a composite check for npm package evaluation, covering safety, popularity, and size. It explicitly specifies when to use it (e.g., 'is X safe / popular / small') and distinguishes from siblings by noting the NPM ecosystem limitation.

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: 'Use whenever an agent asks...' and states limitations (NPM only, other ecosystems via deps.dev directly). Also explains partial failure behavior and the 5-30s delay for bundlephobia first measurement.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and non-destructive. The description adds significant behavioral context: 200K char limit with truncation flag, BGE-base embeddings, cosine similarity over 500-char overlapping windows, and output details (passages with offsets and scores). No contradictions.

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

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

The description is a single, well-structured paragraph that front-loads the core purpose and then adds technical details. Every sentence contributes useful information without redundancy. Efficient and informative.

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 compensates fully by explaining the return format (top-N passages with character offsets and similarity scores). It also covers technical details, cap, and pairing advice, making it complete for agent decision-making.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by giving examples for the query parameter (e.g., 'supply-chain risk') and clarifying the default limit=5. It enhances 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 verb 'semantic search INSIDE a fetched record' and identifies the resource as a previously fetched record. It distinguishes from siblings by explicitly pairing with 'ask_pipeworx_grounded' and contrasting with searching the whole document.

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

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

The description explicitly states when to use: when the record is too big to cram into the prompt. It also advises pairing with ask_pipeworx_grounded for grounded answers. However, it does not provide explicit when-not-to-use or alternative tools beyond the paired one.

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

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

Annotations indicate idempotentHint=true, but the description does not explain idempotency behavior (e.g., whether duplicate subscriptions return the same ID or create new ones). It does cover delivery constraints like phone verification and SMS cap. The description adds some context but misses key behavioral details 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 front-loaded with the core purpose and return value. It is structured into sections: requirement, types, delivery. However, it is somewhat lengthy (several paragraphs) and could be trimmed slightly without losing essential information. Overall, it is well-organized.

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

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

Given the tool's complexity (multiple types, delivery channels, no output schema), the description provides a comprehensive overview. It explains all types, delivery options, and prerequisites. However, it lacks detail on the exact response structure beyond 'new subscription id,' and does not mention any error cases. Still, it covers most necessary context for an agent.

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

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

Schema coverage is 100%, but the description adds significant value by providing concrete examples for each subscription type (e.g., sec_8k items codes, polymarket_edge topic), detailed delivery channel explanations (including webhook signing and auto-disable after 10 failures), and constraints like phone verification. This goes far beyond the schema's type definitions.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It identifies the specific verb (create), resource (subscription), and action (monitoring). It distinguishes itself from siblings like list_subscriptions and unsubscribe 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 mentions a prerequisite (requires Pipeworx OAuth account) and explains different subscription types and delivery channels. However, it does not explicitly state when to use this tool versus alternatives like recent_alerts or polling, nor does it exclude certain scenarios. The guidance is implicit rather than explicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that the tool returns example questions with tool+argument shapes, drawn from a live catalog, and can be called with no arguments or a topic. 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 front-loaded with alternative phrasings and clear purpose, then details the output and parameters. It is relatively long but well-structured and every sentence adds value. Minor room for tightening.

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

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

Despite no output schema, the description thoroughly explains the return format: category-bucketed example questions with tool+argument shapes. It also covers the full usage context (onboarding, first-time use, topic filtering) and lists example categories.

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

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

Schema coverage is 100% and the description explains the optional topic parameter with concrete focus area examples (finance, pharma, etc.) and the effect of omitting it. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It distinguishes from siblings by mentioning meta-tools like ask_pipeworx, entity_profile, etc.

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

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

Explicitly says to use this FIRST when you don't know what Pipeworx can do, and when to pass the optional topic parameter. It names alternatives (ask_pipeworx, entity_profile, compare_entities) and provides concrete examples of usage.

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

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

Description adds detail beyond annotations: explains row is deactivated (not deleted), preserving historical events. Annotations (destructiveHint=false, idempotentHint=true) are consistent and description enriches understanding.

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 covering purpose, constraint, and effect. No wasted words, front-loaded key 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?

Tool is simple (one param, no output schema). Description fully covers purpose, ownership, and behavioral nuance, making it complete for selection and 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 already covers 100% of parameter (id with description). Description adds slight context ('returned by subscribe') but minimal extra value beyond schema.

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

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

Description clearly states 'Cancel a subscription by id' with specific verb and resource. Distinguishes 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?

Explicitly states ownership enforcement: 'you can only cancel your own subscriptions'. Provides clear condition for use but does not explicitly mention 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds valuable context: data sources (SEC EDGAR + XBRL), return values (verdicts, structured form, citation, delta), and scope limitations (US public companies). 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?

Short, front-loaded with trigger phrases. Every sentence provides unique value: description, use case, scope, and capabilities. No redundancy.

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

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

Given single parameter and no output schema, description fully explains input type, output structure (verdict types, extracted value, delta, citation), and domain. Complete for agent decision-making.

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 'claim' fully (100%). Description adds natural-language examples and specific format expectations, going beyond schema to explain the type of claim content (company-financial).

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

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

Description clearly states verb ('validate claim'), resource ('claim verification against authoritative sources'), and gives trigger phrases. It distinguishes from siblings by being the only tool for fact-checking claims.

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...needs to check whether something is factually correct' and describes replaced workflow. Lacks explicit when-not-to-use, but scope is well-defined (company-financial claims).

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