Data Nashville

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

Annotations already declare readOnlyHint=true, idempotentHint=true, so the description's main transparency contribution is the return format ('per-model {score, confidence, signals, raw_response} + combined view') and the cost/default model info. This adds meaningful context beyond annotations.

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

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

The description is a single concise paragraph, front-loaded with the main purpose, and each sentence adds necessary information (purpose, default behavior, optional parameters, use cases). No wasted words.

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

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

Given 4 parameters (all described), no output schema, and a complex task (probing multiple LLMs and scoring), the description adequately explains the tool's behavior, output structure, and parameter usage. It covers all key aspects without needing an 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?

With 100% schema coverage, baseline is 3. The description adds value by explaining the default model (Workers AI Llama-3.3-70b), that Anthropic requires a BYO key, and the context parameter's purpose. This goes beyond the schema descriptions.

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

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

The description uses specific verbs ('probe', 'score') and clearly identifies the resource ('LLMs', 'visibility') and output format. It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on per-model scoring and API usage details.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use optional parameters (e.g., `_apiKey` for Anthropic). However, it does not explicitly compare with sibling tools like scan_competitor_ai_presence, which may have overlapping functionality.

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 safety (readOnly, idempotent); description adds valuable details like routing to 4,482 tools, returning citations, and being fast, which enriches understanding 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?

Long but well-structured with a front-loaded imperative, clear examples, and sibling comparisons. Some redundancy but each section serves a purpose.

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

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

Given the tool's complexity (router to many sources) and lack of output schema, the description covers purpose, usage, examples, and output format (citations) thoroughly.

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

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

Schema coverage is 100% with all parameters described as aliases for 'question'. The description does not add new semantic info beyond what the schema provides, so meets baseline.

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

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

The description clearly states it answers factual questions across many domains (SEC filings, FDA data, etc.) by routing to thousands of sources, and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly guides to prefer over web search, lists example queries, and advises when to step up to alternative tools for more grounded or broad queries.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description reveals the exact process (routing, strict answer extraction from tool result), return structure with evidence and refusal reasons, and the extra LLM call cost. No contradiction with annotations; they are consistent.

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

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

The description is a single focused paragraph that efficiently communicates purpose, process, usage guidelines, and cost trade-off without wasted words. Logically structured with 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?

Given the tool's complexity (routing over 4000 tools, high-stakes usage, no output schema), the description thoroughly covers what the tool does, how it works, when to use it, and what output to expect (including refusal reasons). The agent can fully understand invocation context.

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

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

Schema coverage is 100% with descriptions for all parameter aliases. The description adds only that the question is in natural language, which is already apparent. Baseline for high coverage is 3; the description does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and explains the process of tool routing, argument filling, and answer extraction. It distinguishes from its sibling 'ask_pipeworx' by specifying the grounded mode and return format with evidence and refusal reasons.

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: 'whenever an answer will be quoted, cited, or acted on' and provides concrete examples (financial verdicts, legal claims, etc.). Also tells when not to use: 'prefer ask_pipeworx for casual lookups' due to extra cost, giving clear alternative.

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

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

The description extensively discloses behavioral traits beyond annotations: resolution confidence handling, parent event extraction, news fallbacks, safety short-circuits for low-confidence matches, closed market detection, wide spread warnings, and cancellation rule parsing. It is fully consistent with annotations (readOnlyHint, idempotentHint, non-destructive).

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

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

The description is very long and detailed, with multiple sections in all caps. While it is well-structured and informative, it is not concise. Every sentence serves a purpose, but it could be streamlined for quicker consumption.

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, high parameter count, and lack of output schema, the description is exceptionally thorough. It covers input flexibility, internal resolution logic, edge cases (closed markets, low confidence, wide spreads), cancellation rules, and response shapes. No gaps remain.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the market parameter's flexible input formats and the impact of depth and include_raw on behavior (e.g., quick vs thorough fan-out, raw payloads). This goes beyond schema descriptions, so a 4 is warranted.

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

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

The description clearly states the tool's purpose: to research a Polymarket bet by pulling relevant Pipeworx data in one call. It specifies the input formats (slug, URL, question text) and output (evidence packet + market-vs-model comparison), distinguishing it from sibling tools like polymarket_edges or polymarket_arbitrage by being a comprehensive research tool.

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

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

The description provides explicit usage examples: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also lists classifiers and fan-out examples, giving clear context. However, it does not explicitly state when not to use this tool or compare it to siblings, which would be ideal for a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds context: it pulls from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts by primary metric, and returns paired data with citation URIs. No contradiction with annotations.

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

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

The description is a single dense paragraph that contains a lot of useful information, but lacks structure (e.g., bullet points or clear sections). It is not overly long but could be more scannable.

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 comparing entities with different data sources and no output schema, the description sufficiently covers what data is returned (revenue, net income, etc. for companies; adverse-event counts for drugs) and that results are sorted and include citation URIs.

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

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

Schema coverage is 100%. The description explains the 'type' enum (company vs. drug) and what data each retrieves, and clarifies that 'values' are tickers/CIKs for company or drug names. This adds meaning beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, using specific verbs like 'compare', 'pulls', and 'sorted'. It distinguishes from siblings by explicitly preferring over sequential single-pack 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 concrete query examples ('X vs Y', 'rank these companies') and insists on preferring this tool over sequential lookups. However, it does not explicitly state when not to use the tool or mention alternative tools for different comparison needs.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description discloses account requirements, paid plan for 'thorough', parallel decomposition, return format (findings packet with evidence, gaps, citations), and expected latency (15-60s). No contradiction with annotations.

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

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

The description is long but well-structured with critical info front-loaded (account requirement, core function, use cases, alternatives). Every sentence adds value, though could be slightly more concise given the high information density.

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 (2 params, no output schema), the description is extremely complete: it explains return format, latency, constraints, limitations, and alternatives. It fully compensates for the lack of an 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?

While schema covers both parameters with descriptions, the tool description adds significant value by explaining depth enum behavior (quick=3, standard=5, thorough=8) and stating that broad/multi-part questions are acceptable. This goes beyond what schema provides.

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

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

The description clearly states the tool performs grounded multi-source research across 1129 structured data sources in one call, and distinguishes it from open-web search and sibling tools like ask_pipeworx.

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

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

Explicitly guides when to use (broad/multi-part structured questions) and when not (single lookup, breaking news), and provides specific alternatives (ask_pipeworx). Also explains account requirements and depth tier availability.

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, etc. The description adds value by stating that results 'are ready to call directly, no second schema lookup needed', which explains the output behavior beyond annotations. 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 approximately four sentences, front-loaded with the core purpose, and every sentence adds value. No redundant or vague statements.

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 compensates for the lack of output schema by explaining return format (tools with names, descriptions, full schemas) and notes aliases for parameters. It adequately covers the tool's functionality for a discovery tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters well. The description provides examples and notes aliases, but does not add significant new meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Find' and the resource 'tools', listing specific domains (SEC filings, financials, FDA drugs, etc.) and explaining that it returns top-N relevant tools with full schemas. This differentiates it from sibling tools which are specific domain tools.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and advises to 'Call this FIRST when you have many tools available'. It provides clear context for when to use, though it does not explicitly state when not to use.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds valuable context: it explains the multi-source fan-out, specific return fields, the soft-fail for patents until May 2025, and the GDELT→GNews fallback for news. 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 detailed and front-loaded with example queries, but it is somewhat lengthy. However, every sentence provides necessary information, so it is effective if not maximally concise.

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

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

Given the tool's complexity (multiple data sources, fallbacks, limitations), the description covers return structure, error handling for patents, and expected outputs. No output schema exists, but the description compensates well.

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

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

Schema coverage is 100%, but the description adds meaningful examples and constraints: explains that type is only 'company', value is ticker or zero-padded CIK, and that names are not supported. 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 it provides a 'full cross-source profile of a US public company' and gives specific example queries. It distinguishes itself from chaining single-pack lookups, making the purpose unmistakable.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and instructs to use resolve_entity if only a name is available, providing clear when-to-use and when-not-to-use guidance with a sibling tool reference.

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. The description adds behavioral context about clearing stale or sensitive data, which is useful beyond annotations. No contradictions.

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

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

Two concise sentences: first states function, second provides usage guidance. No fluff. Each sentence earns its place.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, and behavioral context. Sibling tools are referenced for completeness.

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

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

Schema coverage is 100% with well-described parameter 'key'. The description adds no additional meaning beyond the schema's 'Memory key to delete'. Baseline score of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key', which is a specific verb and resource. It distinguishes from sibling tools like 'remember' and 'recall' by focusing on 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?

Explicitly states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also mentions pairing with remember and recall, providing 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=false, indicating a safe, non-destructive operation. The description adds behavioral details: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This goes beyond annotations without contradicting them.

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

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

The description is very concise: two sentences plus a bulleted list. It front-loads the main action and efficiently conveys purpose, process, and use cases without extraneous words.

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

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

For a tool with 2 parameters, no output schema, and safety annotations, the description is nearly complete. It explains the process (fetch, extract, output) and the output format (single text blob in llms.txt format). It could briefly mention that no actual file is written, but given annotations, this is 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%; both parameters (url, max_links) have descriptions in the schema. The description does not add parameter-specific insights beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for a given URL. It specifies the action ('generate'), the resource ('llms.txt file'), and the target ('any URL'). This distinguishes it from sibling tools like 'scan_competitor_ai_presence' which focus on auditing rather than generating.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting llms.txt for one's own project, or auditing a competitor. While it doesn't mention when not to use it or name alternatives, the use-case list provides clear context for when the tool is appropriate.

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 a safe read-only operation (readOnlyHint, idempotentHint, destructiveHint false). The description adds value by listing the returned fields and the default behavior (active subscriptions). However, it does not mention potential pagination or ordering, but the low complexity reduces the need.

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 with no redundant information. It front-loads the action and result, lists fields efficiently, and closes with actionable use cases. Every sentence earns its place.

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

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

The description covers the essential aspects for a list tool with one parameter: purpose, returned fields, and use cases. It could optionally mention whether results are paginated, but given the simplicity and annotations, it is sufficiently complete.

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

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

Schema description coverage is 100% with a clear description for the single parameter 'include_inactive'. The tool description adds minimal new meaning beyond implying the default to active subscriptions when not specified.

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 the caller's subscriptions, specifies the returned fields, and distinguishes its purpose from sibling tools like subscribe and unsubscribe. The verb 'List' and resource 'subscriptions' are precise, and the context of reviewing before adding or finding an ID to cancel adds clarity.

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 use cases: 'review what you're monitoring before adding more' and 'find an id to cancel.' It implies when to use this tool (before subscribe/unsubscribe) but does not explicitly state when not to use it or provide alternatives, which is acceptable given the clear context.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds behavioral details: the tool lists either known services or layers for a given service, and returns id + name. No contradictions, and the description 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?

Three concise sentences: first states purpose, second explains usage with example, third states output. No unnecessary words, information 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?

For a simple tool with one optional parameter and no output schema, the description fully covers input usage, output content, and relation to sibling tools. It is self-contained and complete.

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

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

The single optional parameter 'service' has 100% schema coverage. The tool description adds concrete examples (crime, service_requests, permits, full path) and clarifies the behavior when omitted, significantly enriching the schema's meaning.

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

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

The description clearly states the verb 'List', the resource 'layers of a Nashville ArcGIS service', and the purpose 'for discovery'. It distinguishes from siblings like nashville_query and nashville_recent by explaining the output is used for subsequent queries.

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

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

The description explains when to omit the service parameter (to list known services) and provides examples of valid inputs. It also notes the output format for use with nashville_query, giving clear context. However, it does not explicitly state when not to use this tool vs 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 and idempotentHint. Description adds behavior like 'Epoch dates are converted to ISO' and mentions default/max limit, providing useful context beyond annotations.

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

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

Three sentences: first defines purpose, second lists capabilities, third gives usage tips and a key behavior. No fluff, 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?

Covers purpose, usage, key parameters, and special behavior. No output schema, but description is adequate for a query tool. Could mention response structure but not critical.

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

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

Schema coverage is 100%, but description adds value by noting default values (limit=100, where='1=1'), short names for service, and max limit (2000), which are not in 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 explicitly states 'Query any Nashville ArcGIS layer by service path + layer id' and lists capabilities (where, out_fields, order_by, limit). It distinguishes from siblings by directing users to nashville_layers and nashville_recent for discovery.

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?

Clearly indicates when to use (to query ArcGIS layers) and references alternatives (nashville_layers, nashville_recent) for finding layers. Lacks explicit 'when not to use' but sufficient context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details beyond annotations: returns latest rows newest-first, epoch dates converted to ISO. This provides useful context about ordering and date formatting that annotations don't cover.

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

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

The description is two sentences plus a brief usage recommendation. It is front-loaded with purpose, then usage guidance. Every sentence adds value without redundancy or fluff.

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

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

Given three parameters, no output schema, and annotations covering safety, the description is complete. It states what is returned (latest rows), ordering (newest-first), and date format (ISO). It also references sibling tools for additional capabilities, ensuring the agent has enough context.

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

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

Schema coverage is 100% with all three parameters described. The description adds context beyond schema: it explains that 'where' is an ArcGIS SQL filter and that the tool returns epoch dates converted to ISO. This provides semantic understanding of how parameters affect behavior.

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

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

The description clearly states the tool returns recent records from specific Nashville open datasets (crime, 311) by friendly name, with specific verb 'retrieves' and resource identified. It distinguishes from siblings by explicitly recommending this tool over web search for recent data and directing other layers to nashville_layers and nashville_query.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' for specific queries and provides guidance on filtering with 'where' and alternatives for other layers. It clearly states when to use this tool versus siblings, making it easy for the agent to decide.

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

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

Beyond the annotations (all false), the description reveals key behaviors: rate-limited to 5 per identifier per day, free (no quota usage), and that feedback is read daily and influences the roadmap. This adds significant context annotations do not 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 concise, using three clear sentences plus a list of types. It front-loads the purpose and usage. Slightly more structure (e.g., bullet points for examples) might improve scannability, but it's efficient overall.

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

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

Given the tool has no output schema, the description covers all necessary aspects: what to submit, what to avoid, rate limits, impact, and optional context. It is complete enough for an agent to use correctly without confusion.

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 meaning of each 'type' value in context and advising not to include end-user prompts. This enhances the schema descriptions, justifying a score above baseline 3.

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

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

The description explicitly states the tool's purpose: sending feedback about bugs, missing features, data gaps, or praise. It clearly distinguishes itself from sibling tools by being a feedback mechanism rather than a query or search tool.

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

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

The description provides explicit guidance on when to use each feedback type (bug, feature, data_gap, praise) and what not to include (avoid pasting end-user prompts). It effectively tells the agent when and how to use the tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, etc. Description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h), and self-aggregating signal. 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?

Description is several sentences but each sentence adds value. Well-structured with bullet-like points, no fluff. Could be slightly more concise but still 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?

Despite no output schema, description explains return types (top tools, top packs, total call volume) and caching behavior. Low complexity with one param; description is complete for agent decision 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 fully describes the single parameter (window) with enum. Description adds context: shorter windows surface hot trends, longer windows show steady-state demand, enhancing understanding beyond schema.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window, distinguishing it from siblings like ask_pipeworx (analysis) and discover_tools (discovery).

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 given: discovering hot data sources, confirming popular tool canonical, and aligning use case with agent needs. Lacks explicit when-not-to-use, but guidance 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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds rich behavioral details: the atomic checks (monotonicity, partition sum, semantic anchor, partition filter, fill check), conditions for actionable signals, and when not to trade. 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 quite long and contains many technical details. While well-structured with paragraphs and bold for emphasis, it could be more concise. The first sentence effectively front-loads the requirement and purpose, but the verbosity reduces clarity.

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

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

Covers both modes, constraints, response structure, and references sibling tools for further actions. Mostly complete, but lacks explicit details on cross-event return shape and error cases beyond 'no args fails'. Overall adequate 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% with descriptions explaining each parameter's role. The description adds significant value by explaining the logic behind each mode, recommended usage, and behavioral implications (e.g., cross-event mode catches patterns single-event misses). This goes 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?

Clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks, with two distinct modes (event/topic). Examples provided. Differentiates from siblings like polymarket_edges and polymarket_fill_risk by mentioning them for related but distinct purposes.

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

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

Explicitly states which parameter to use for which scenario: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. Warns that calling with no args fails. Suggests using polymarket_fill_risk for custom sizing, providing clear guidance on when to use this 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 indicate read-only, idempotent, open-world, non-destructive. The description adds extensive behavioral context: cache duration (1h), response structure (by_segment with diagnostics), model methodologies, edge calculation details, and tradeable-edge knobs. 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 extremely verbose and dense, containing technical model formulas and detailed explanations that go beyond what an agent needs for selection. While well-structured, it sacrifices conciseness, making it less efficient for quick comprehension.

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

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

Given the tool's complexity (9 parameters, no output schema, multiple segments), the description is highly complete. It covers caching, response structure, model families, edge cases (fed markets, empty segments), and diagnostics, ensuring agents fully understand behavior.

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% (all 9 parameters documented). The description adds operational context for key parameters (e.g., 'Tradeable-Edge Knobs' section explains min_liquidity, max_spread_pp, min_partition_leg_kelly beyond schema descriptions), providing moderate 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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, explicitly for 'what should I bet on today'. It distinguishes from siblings by explaining three unique segments (model-driven, structural arbitrage, concentrated longshot).

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 provides usage context ('what should I bet on today') and describes when it's appropriate. It does not explicitly list when not to use or mention alternatives, but the detailed segment descriptions imply differentiation.

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

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

Adds significant context beyond annotations: snapshots written on cache-miss, gaps mean no scan, decay from daily closes not intraday, and history bounded by 60-day TTL. No contradiction with annotations (readOnlyHint, etc.).

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

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

Length is appropriate for the complexity; front-loaded with key purpose. Uses formatting (dashes, newlines) to organize response fields. Could be slightly trimmed but every sentence adds necessary information.

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

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

No output schema, but description thoroughly explains response structure (tracked[], expired[], snapshot_dates[]) with field semantics and units. Covers limits and data source behavior. Complete for a 2-parameter tool.

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

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

Schema coverage is 100%, but description adds defaults (days default 14, window default '1wk'), clamp behavior (days max 30), and explanation of what each parameter does in context. Adds value beyond raw 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 it provides 'edge persistence and decay telemetry' from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes from sibling 'polymarket_edges' by focusing on historical trends rather than current snapshots.

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 (e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades') and mentions limitations (60-day TTL, snapshot gaps). Does not explicitly list alternatives or when not to use, but the purpose is clear enough.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) indicate safe read-only operation. Description adds behavioral details: walks order book ladder, returns specific fields like top_of_book, vwap, slippage, and discusses risks like thin legs and directional risk. 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?

Well-structured with clear sections for requirements, single-market, basket, and usage recommendation. Front-loaded with core purpose. However, it is verbose; some details could be condensed without losing meaning. Still, every sentence is 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?

Given tool complexity (two modes, 4 parameters, no output schema), description is thorough. It lists return fields, explains mode differences, and covers edge cases like thin legs and directional risk. Complete for agent decision-making 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 has 100% description coverage for 4 parameters. Description adds meaning: clarifies modes based on market vs event, explains default side logic for baskets, and interprets size_usd differently for single-market vs basket. Enhances schema info.

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

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

The description clearly states the tool checks realizable vs theoretical edge against live order book depth, distinguishes between single-market and basket modes, and specifies it's for use before acting on arb signals or trades above ~$500. It differentiates from sibling tools like polymarket_arbitrage and polymarket_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?

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Explains why via risks of thin books and partial baskets creating directional exposure.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, non-destructive) are already informative. The description goes far beyond by detailing safety fields (compatibility_warning, temporal_alignment, skipped_cross_type), explaining edge cases, and honestly noting that most pre-mapped topics currently return warnings. 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 well-structured and front-loaded with the core concept. It is relatively long but each section earns its place (modes, response, safety). Minor verbosity in the safety field explanation could be trimmed without losing essential context.

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

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

Given no output schema, the description thoroughly explains the response structure, including leg-by-leg prices, top spreads, compatibility warnings, temporal alignment, and skipped counters. It covers edge cases and provides sufficient context for an agent to interpret results correctly.

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

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

Input schema has 100% coverage with descriptions for all 3 parameters. The description adds value by explaining topic values and the overriding behavior of explicit params, which the schema alone does not fully convey. This provides meaningful semantic enrichment beyond the baseline.

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

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

The description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes and explains the core function with a specific verb+resource. While sibling tools like polymarket_arbitrage exist, the unique cross-venue focus and detailed explanation distinguish it effectively.

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

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

The description explicitly explains when to use each mode (topic vs explicit) and provides warnings about compatibility, temporal alignment, and the rarity of real spreads. It does not explicitly state when not to use the tool, but the context and caveats give clear guidance on appropriate usage.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral details: scoping to identifier, listing all keys when omitting argument, and the retrieval nature of the tool, which 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?

Two sentences that are front-loaded with purpose. Every sentence adds value: purpose, usage guidance, scoping, and pairing with sibling tools.

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

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

For a tool with one optional parameter and no output schema, the description covers return behavior (value or list of keys), scoping, and pairing with related tools. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context like 'omit the key argument to list all keys', which is already in the schema's parameter description. No significant new meaning beyond the schema.

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

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

The description clearly states the verb 'retrieve' or 'list' and the resource 'values saved via remember'. It distinguishes from the sibling tools 'remember' and 'forget' by explicitly mentioning them and the action pair.

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

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

The description provides clear usage context: 'Use to look up context the agent stored earlier' and examples of when to use it. It does not explicitly state when not to use, but the pairing with remember/forget gives implied 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 adds context beyond annotations by explaining that mark_read:true flags events as read, altering future calls. This is a behavioral side effect not captured by readOnlyHint=true, which suggests read-only. The description mitigates this by clarifying the side effect.

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 at five sentences, front-loaded with the purpose, and each sentence adds meaning—no filler. It efficiently covers purpose, return fields, parameters, side effects, and alternatives.

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

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

Given no output schema, the description sufficiently outlines return fields and behavioral notes. It lacks detailed return format or examples but provides enough for basic usage. The alternative endpoint mention adds completeness.

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

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

With 100% schema coverage, the description adds value by providing concrete examples (e.g., type 'sec_8k'), explaining the effect of mark_read on subsequent calls, and clarifying that since is an ISO timestamp. This goes beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, returns most recent alerts with specific fields, and allows filtering by type and since. It distinguishes from siblings like list_subscriptions by focusing on reading alert content rather than managing 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?

The description mentions polling is fine and provides an alternative REST endpoint, implying when to use this tool over direct API access. However, it does not explicitly state when not to use it or compare with sibling tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive, and open world. The description adds significant behavioral context: fan-out to multiple sources, fallback logic, soft-fail for USPTO, and return structure (changes[] grouped by source, count, URIs), which is 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 a single, well-structured paragraph. It front-loads example queries, explains sources, parameter details, return format, and alternative tool, all in about 100 words. Every sentence is informative with no redundancy.

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

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

Despite no output schema, the description thoroughly covers what the tool returns (changes grouped by source, total_changes, citation URIs). It explains sources, limitations, and alternative. It is complete for an agent to use correctly.

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

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

With 100% schema description coverage, baseline is 3. The description adds extra value by explaining that 'since' accepts ISO date or relative shorthand and suggests typical monitoring values ('30d', '1m'), and that 'value' can be ticker or CIK. This exceeds schema details.

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

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

The description clearly defines the tool as a change feed for a company, listing specific example queries and distinguishing it from the sibling tool entity_profile. The verb 'return' and resource 'change feed' are explicit.

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

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

The description provides explicit when-to-use examples (query patterns) and a clear alternative ('Use entity_profile instead...'). It also details fallback behavior for GDELT→GNews and notes soft-fail for patents, giving comprehensive usage guidance.

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

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

Beyond annotations (idempotentHint=true, destructiveHint=false), description adds behavioral context: key-value pairs scoped by identifier, persistence differences (24h for anonymous vs persistent for authenticated). 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?

Four sentences, each earning its place: purpose, when-to-use, storage behavior, pairing instructions. No fluff, front-loaded with the main action.

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 2-parameter tool with no output schema, description covers all relevant context: storage mechanism, scope, persistence duration, and relationships with sibling tools. Nothing missing.

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

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

Schema already documents both parameters with descriptions, so baseline is 3. Description adds value by giving concrete examples of keys ('subject_property', 'target_ticker', 'user_preference'), which helps the agent understand typical 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?

Description starts with a clear verb+resource combination ('Save data') and specifies the scope ('across this conversation or across sessions'). It distinguishes itself from sibling tools like recall and forget, which are explicitly mentioned for retrieval and 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?

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward.' Also clearly states pairings: 'Pair with recall to retrieve later, forget to delete.' This helps the agent decide between tools.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds that it cascades through several endpoints internally and returns citation URIs. No contradiction; description enriches behavioral 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?

The description is a single coherent paragraph, front-loaded with examples. Slightly longer than necessary but well-organized and informative. Every sentence adds value.

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

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

Given no output schema, the description adequately specifies return values for both types. Covers purpose, input formats, and internal behavior. Minor gap: no mention of error handling or edge cases, but overall sufficient for a resolver tool.

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

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

Schema coverage is 100% with clear descriptions. The description adds context: for company accepts ticker, CIK, or name with auto-disambiguation; for drug accepts brand or generic name. Also details what each type returns, compensating for lack of output schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers needed by other tools. It provides concrete examples and specific output for each type (company returns ticker+CIK, drug returns RxCUI). This distinguishes it from siblings like entity_profile which likely provide detailed info rather than identifiers.

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

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

Explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It explains that it replaces manual lookups. However, it doesn't explicitly contrast with alternatives or mention when not to use it (e.g., if you already have the ID, use entity_profile). Still provides clear context.

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

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

Description goes beyond annotations (readOnlyHint, etc.) by explaining that it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also details the returned data (score, confidence, signal density). No contradictions with annotations.

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

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

Three sentences: purpose, method, use case. Front-loaded with core action. No unnecessary words. Each sentence earns its place.

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

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

Despite no output schema, description fully explains return format (ranked list with score, confidence, signal density). Covers required inputs and behavioral aspects. No 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%, so baseline is 3. Description adds value by specifying that entities array should be 2-8 items and first is treated as subject. Also clarifies models and apiKey usage. These details supplement the schema.

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

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

Clearly states it compares AI visibility across multiple entities side-by-side, distinct from sibling ai_visibility_check which checks a single entity. The verb 'compare' and resource 'AI visibility' are 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?

Provides clear context ('competitive AI-marketing audits') and an example question. While it doesn't explicitly state when not to use or name alternatives, the purpose is well-defined and implies use case.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds key behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed listed upon timeout. No contradiction with annotations.

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

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

The description is a single dense paragraph. While every sentence adds value, it could be slightly more structured (e.g., bullet points for return fields). Still efficient and front-loaded.

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

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

No output schema, but description thoroughly explains return fields (summary block, per-advisory detail, links, alternative versions) and error behavior. Covers all needed context for an 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% with both parameters described. Description adds that scoped packages like '@types/node' are accepted for package, and that version defaults to latest when omitted.

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

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

The description specifies the composite check for adding an npm package, aggregating from deps.dev and bundlephobia. It clearly distinguishes from sibling tools (no other scan_* tool exists in the list) and uses specific verbs like 'fans out across'.

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: 'is X safe / popular / small' or 'what does adding lodash cost me'. Also provides exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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) indicate safety. The description adds rich behavioral context: embedding model (BGE-base-en), windowing (500-char overlapping), cosine similarity, character offset for verification, and a 200K char cap with truncation flag. 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 remarkably concise: 3 sentences covering purpose, usage, technical details, and pairing. Every sentence serves a purpose, no redundancy, and the key action 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?

For a tool with no output schema and 3 parameters, the description fully explains input, output (passages with offsets and similarity scores), internal mechanism, constraints, and integration with sibling tools. Nothing crucial is missing for correct invocation.

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

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

Schema coverage is 100% with good descriptions. The description adds value by providing real-world examples for 'text' (e.g., SEC 10-K body) and 'query' (e.g., 'supply-chain risk'), and clarifies 'limit' default (5) and range (1-20). This enhances natural-language understanding beyond schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and distinguishes from sibling tools like 'ask_pipeworx_grounded' by explaining it saves context when records are too large. It specifies the verb 'search' and the resource 'record' with a clear scope.

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

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

The description provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt'. It also mentions pairing with 'ask_pipeworx_grounded' but does not explicitly list when not to use or alternative tools for small records.

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

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

The description discloses behavioral traits beyond annotations: it requires OAuth, details type-specific parameter structures, and explains delivery channel behaviors including rate limits, verification requirements, webhook signing, and auto-disable after failures. 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 well-structured and front-loaded with the primary purpose and return value. It is somewhat lengthy but each paragraph serves a distinct purpose. Could be slightly trimmed without losing clarity, but overall effective.

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

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

Given the tool's complexity (3 parameters with nested objects, 5 types, multiple delivery options) and no output schema, the description is comprehensive. It covers account requirements, type-specific filtering, delivery channel mechanics, and the return value. No gaps identified.

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's params and detailed explanations for delivery channel properties (e.g., phone verification process, webhook HMAC signing). This goes well beyond the schema definitions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on the creation action and providing specific types and delivery channels.

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 requires a Pipeworx OAuth account, lists supported subscription types with examples, and details delivery channel limitations (e.g., SMS 10/day cap, phone verification, webhook auto-disable). While it does not explicitly exclude other tools, the context clarifies when to use this 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?

Description details the output: category-bucketed example questions with exact tool and argument shape. Annotations already declare readOnly, openWorld, idempotent, non-destructive; description adds rich behavioral context 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?

Description is somewhat lengthy but well-structured with front-loaded purpose and clear categorization. Every sentence adds value, though minor trimming could be 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?

Despite lacking an output schema, the description fully explains the return shape (category-bucketed example questions with tool+argument shapes). No additional context is needed 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?

Single parameter 'topic' is fully described in schema (100% coverage) and description adds meaning by listing possible values and explaining the effect of omission.

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 is an onboarding entry point that returns category-bucketed example questions with tool and argument shapes. It distinguishes from siblings by explicitly naming the use case of discovering what Pipeworx can do.

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

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

Explicitly instructs to use this tool FIRST when the agent doesn't know what Pipeworx can do, and provides guidance on when to omit or pass a topic argument. No alternatives are needed as it's the designated onboarding tool.

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

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

Adds significant behavioral context beyond annotations: soft deactivation (not deletion), historical events remain available via recent_alerts. Aligns with idempotentHint=true and destructiveHint=false.

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

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

Two sentences, no wasted words, front-loaded with action and key constraint. 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?

Covers the tool's simple interface well: ownership, effect, and relationship to recent_alerts. Could mention error handling (e.g., non-existent id), but not essential.

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

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

Schema coverage is 100%, so description adds limited value. However, it notes that the id is 'returned by subscribe', providing a useful origin. Baseline 3 is appropriate.

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

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

States 'Cancel a subscription by id' clearly, with ownership enforcement and deactivation detail. 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?

Specifies ownership enforcement ('you can only cancel your own subscriptions'), clarifying when the tool applies. Does not explicitly list when not to use, but context is sufficient.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds context about the return value (verdict with citation and delta), its efficiency (replaces multiple calls), and domain support (v1: company-financial claims). 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 well-structured, front-loading the purpose with examples, then giving usage guidance, and finally details on scope and returns. Every sentence adds value. It is slightly verbose but remains clear and helpful.

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

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

Given the single parameter, no output schema, and comprehensive annotations, the description covers the tool's purpose, usage, domain, and return value. It slightly lacks details on handling out-of-domain claims or error conditions, but the information provided is sufficient for an AI agent to decide when 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?

The single parameter 'claim' has a good schema description mentioning natural-language and examples. The description further adds context by stating that the claim is in natural language and can be phrased in various ways. With 100% schema coverage, the description adds additional 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 function as natural-language claim verification, provides example usage phrases ('Is it true that...', 'fact check'), and distinguishes it from sibling tools by being claim-specific. It also mentions it replaces 4-6 sequential calls, further clarifying its unique role.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes the domain limitation to company-financial claims. While it doesn't explicitly state when not to use, the domain scope implies it. No explicit alternatives are mentioned, but the tool's uniqueness makes this acceptable.

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