Owasp

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

Description adds return format details (per-model score, confidence, signals, raw_response, combined view) and clarifies that Anthropic API key is passed through. Annotations already indicate safe read-only operation.

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?

Succinct 4-sentence description with front-loaded purpose. Every sentence provides essential information, 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, description explains return format and parameter usage fully. Covers required and optional parameters, use cases, and model limitations.

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 provides extra context: default model info, BYO key for Anthropic, and purpose of context parameter for disambiguation. Adds value beyond schema.

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

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

Description clearly states the tool probes LLMs to score visibility (0-100) for a given entity, distinguishing it from sibling tools like ask_pipeworx or deep_research. Specific verb 'probe' and resource 'LLMs' with output format.

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

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

Explicit use cases provided (AI-marketing audits, pre-launch brand checks, competitive monitoring). Default model and optional Anthropic usage explained. Lacks explicit when-not-to-use, but context is clear.

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

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

Annotations already provide readOnlyHint, openWorldHint, etc. The description adds significant context: routes to 4476 tools, returns structured answer with citation URIs, 'one fast call'. Does not contradict annotations.

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

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

The description is lengthy with multiple paragraphs and many examples. It is front-loaded with the key directive but could be more concise. Acceptable but not exemplary.

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 across many sources), the description is comprehensive: covers use cases, behavior, alternatives, and examples. No output schema needed.

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

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

Schema description coverage is 100% with aliases well documented. The description provides examples but does not add meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it handles questions about current/historical data from many sources, distinguishing it from siblings like ask_pipeworx_grounded and deep_research. It uses specific verbs and lists numerous example query types.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', with clear guidance on when to step up to alternatives. Provides examples and trigger phrases ('what is', 'look up', etc.).

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, openWorldHint=true, idempotentHint=true. The description adds rich behavioral details: refusal mechanism, return structure with evidence/confidence/refusal reasons, and cost implications. 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 a single, well-structured paragraph. It front-loads the key distinction (hallucination-resistant) and efficiently covers purpose, usage, behavioral transparency, and return structure. Every sentence earns its place.

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

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

Given no output schema, the description fully explains the return object (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal reasons. It also mentions the extra LLM call cost, making it complete for 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. The description mentions that the question accepts multiple aliases, which is already in the schema descriptions. It adds no new parameter semantics 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 it's a 'Hallucination-resistant answer mode for high-stakes reads.' It explains the mechanism (picks tool, fetches data, extracts answer) and distinguishes from ask_pipeworx, making the purpose very specific and differentiating from siblings.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and when not (casual lookups prefer ask_pipeworx). Provides clear context and 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, establishing the safety profile. The description adds that the tool returns a table of contents with names and counts, which is consistent and provides some additional behavioral context.

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

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

The description is two concise sentences. The first sentence defines the tool's output, and the second sentence gives usage guidance. No unnecessary information, perfectly 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?

Given zero parameters and no output schema, the description sufficiently explains what the tool returns (chapter names and counts per level) and how it relates to the sibling tool asvs_requirements. It is complete for an agent to understand usage.

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

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

There are no parameters, so the description does not need to add parameter details. It effectively communicates the tool's function without needing to clarify parameter semantics, consistent with the baseline of 4 for zero parameters.

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

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

The description clearly states the tool returns a table of contents for OWASP ASVS 5.0 with 17 chapters (V1–V17), including names and requirement counts. It distinguishes from the sibling tool asvs_requirements by specifying its role as a discovery mechanism.

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

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

The description explicitly says 'Use to discover which chapter to pull with asvs_requirements,' providing direct guidance on when and how to use this tool in conjunction with its sibling, making the usage context very clear.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) already indicate a safe, non-destructive operation. The description adds that it returns verification id, section, level, and text, which is consistent with annotations and provides context about the response structure.

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

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

The description is concise (two sentences), front-loaded with the tool's value, and every sentence contributes essential information. No unnecessary words.

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

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

Given four optional parameters and no required ones, the description covers what the tool returns (verification id, section, level, text) despite no output schema. It is complete enough for an agent to understand the tool's purpose and usage.

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

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

All parameters have descriptions in the schema (100% coverage). The description reinforces their purpose by stating 'Filter by chapter, level and/or keyword' and gives keyword examples ('password', 'TLS', 'CSRF'), adding meaningful context 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 provides testable security requirements from OWASP ASVS 5.0 with specific attributes (verification id, section, level, text). It positions itself as the 'citable controls layer,' distinguishing it from siblings like 'asvs_chapters'.

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

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

The description explains how to filter by chapter, level, and keyword, and provides an example use case: 'what does ASVS require for password storage?' It does not explicitly mention when not to use or contrast with alternatives, but the usage 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?

The description goes far beyond the annotations (readOnly, idempotent, openWorld, non-destructive) by detailing the internal process: market resolution, classification, fan-out to data sources, response shapes with confidence levels, parent event extraction, news fallback handling, safety checks for low-confidence matches, closed market handling, wide spread warnings, and resolution-rule risk analysis. This comprehensive behavioral disclosure ensures the agent understands all operational details and caveats.

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 paragraphs and separate sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.). While every sentence adds information, the length may impact readability for agents. It is front-loaded with the main purpose, but the density of edge cases and examples makes it less concise than ideal.

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 the complexity (3 parameters, no output schema, and many edge cases), the description covers all necessary aspects: input variations, detailed response shapes, confidence and fallback mechanisms, safety constraints, and resolution rules. It leaves no critical gap for the agent to understand how to use the tool and interpret results.

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

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

Although the input schema already has 100% description coverage for all three parameters (market, depth, include_raw), the description adds valuable context: it explains that 'market' can be a slug, URL, or question text; 'depth' options are 'quick' vs 'thorough' with default; and 'include_raw' includes a recommendation for when to use true versus false, along with payload size implications. This extra meaning justifies a score above the baseline of 3.

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

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

The first sentence clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research) and the resource (Polymarket bet). The description differentiates from siblings by detailing the comprehensive process (resolution, classification, fan-out, evidence packet) and usage examples, making it distinct.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides numerous examples across bet categories. However, it does not explicitly mention when not to use it or suggest alternative sibling tools, which would elevate the score to 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds details beyond annotations: return format (Markdown), behavior on ambiguous topics, and listing all sheets when no topic is given. No contradiction.

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

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

Two sentences, no wasted words. Front-loaded with purpose and context, followed by precise usage details.

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

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

For a simple tool with one optional parameter and no output schema, the description is fully complete. It covers all scenarios: with topic, ambiguous topic, and no topic.

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

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

Schema coverage is 100% with a single parameter description. The description adds value with specific examples ('SQL Injection', 'JWT', etc.) and clarifies behavior when the parameter is omitted (lists all).

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: returns matching cheat sheets as Markdown with a topic (including candidate matches if ambiguous) or lists all sheets without a topic. This distinguishes it from sibling tools like asvs_chapters or top10.

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

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

Explicitly describes two usage modes: with topic (returns specific sheet or candidates) and without (lists all). While it doesn't mention when not to use or compare to alternatives, the context signals provide sufficient guidance for choosing between modes.

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 valuable context: it uses latest 10-K data for companies, handles off-calendar fiscal years, returns paired data with pipeworx URIs. No contradictions.

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

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

The description is front-loaded with compact examples and uses clear, direct language. Every sentence adds value: examples, data sources, edge cases (off-calendar fiscal years), and result format. No redundancy.

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

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

Given the complexity (two entity types, multiple data points) and absence of output schema, the description fully explains returns: paired data with citation URIs, sorting by primary metric. It covers all necessary context for an agent to invoke correctly.

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

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

Schema coverage is 100%, but the description adds meaning beyond schema: it explains what each 'type' value retrieves (financials vs adverse events) and gives examples for 'values' (tickers, drug names). This enriches parameter understanding.

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

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

The description clearly states it performs side-by-side comparisons of 2-5 entities (companies or drugs) in one call, distinguishing it from sequential lookups. It specifies data sources (SEC EDGAR for companies, FAERS for drugs) and how results are sorted.

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 advises to prefer this tool over sequential single-pack lookups when comparing entities. It provides example queries like 'compare X and Y' and 'rank these companies' covering typical use cases.

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

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

Annotations already indicate safe, idempotent, read-only operation. Description adds rich behavioral detail: returns findings packet with verbatim evidence, confidence, source, fetched_at, stable citation, and gaps[] for unanswered facets. Also discloses expected latency (15-60s) and account/plan limitations.

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?

Efficiently front-loaded with critical caveats (account required, alternative). Every sentence adds value—no filler. Well-structured with clear sections for usage, behavioral details, and limitations.

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 only 2 parameters and no output schema, the description thoroughly explains return format, behavioral traits, limitations, and alternatives. Provides complete context for an agent to correctly select and invoke the tool.

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

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

Schema coverage is 100% with good descriptions. Description adds extra context: depth enum values explained with counts and default, and question parameter clarified as natural language suitable for broad multi-part queries.

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

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

Explicitly defines the tool as performing grounded multi-source research across 1127 structured data sources, with decomposition and parallel routing. Clearly distinguishes from sibling ask_pipeworx for single lookups or breaking news.

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

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

Provides explicit guidance on when to use (broad/multi-part questions over structured data) and when not to (breaking news, sign-in issues). Also mentions account/plan requirements and gives alternative tool ask_pipeworx for those cases.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. Description adds valuable context about output: returns top-N tools with full schemas and curated examples, ready to call directly.

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

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

Single paragraph is front-loaded with purpose, then domains, output, and usage advice. Every sentence adds value, though slightly lengthy.

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

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

Given no output schema, description explains return format (names, descriptions, schemas) and usage context. Could mention pagination but overall complete for 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 has 100% coverage with descriptions. Description reinforces by listing aliases and providing examples, adding value beyond the schema.

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

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

The description clearly states the tool 'finds tools by describing the data or task', lists specific domains, and distinguishes itself as a discovery tool to be called first, unlike sibling tools that provide direct answers.

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: 'when you need to browse, search, look up, or discover' and 'Call this FIRST when you have many tools'. Does not provide explicit exclusions or name alternatives, but context is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds valuable context: patents API may sunset May 2025 and soft-fails, data sources, and return format. 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?

Description is dense and front-loaded with examples, but slightly long. Every sentence adds value, so it earns a high score, though it could be slightly more concise.

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

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

Despite no output schema, the description thoroughly explains what is returned (CIK, filings, fundamentals, patents, news, LEI) and data sources. For a complex tool, this provides sufficient context for an AI agent.

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

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

Schema coverage is 100% (2 parameters described). Description adds meaning beyond schema: explains 'value' can be ticker or CIK, that names are not supported, and clarifies the 'type' enum is currently only 'company'.

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

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

Description clearly states the tool returns a 'full cross-source profile of a US public company' in one call, listing specific resources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return fields. Distinguishes from siblings by recommending it over chaining 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?

Explicitly says when to use ('when the user asks for a holistic view') and when not ('names not supported — use resolve_entity first'). Also states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups', providing clear decision guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true; description adds no extra behavioral context beyond stating deletion. No contradiction.

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

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

Two sentences, front-loaded with main action, followed by usage guidance. 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?

Simple tool with one parameter; description fully covers purpose, usage, and sibling context. 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 covers 100% of parameters with clear description; tool description does not add additional meaning beyond what the 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 action (delete), the resource (memory), and the qualifier (by key). It distinguishes from sibling tools like 'remember' and 'recall'.

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

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

Explicitly states when to use (context stale, task done, clear sensitive data) and mentions pairing with siblings 'remember' and 'recall'.

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

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

The description details the operations: fetches page, extracts title/description/links, outputs standard markdown format. Annotations already indicate read-only, idempotent, non-destructive; the description adds valuable behavioral context beyond annotations.

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

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

The description is concise with two sentences and a bullet list. Every sentence is informative, front-loaded with the primary purpose, and no extraneous content.

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

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

Given the tool's simplicity, the description completely explains input, process, output, and use cases. Annotations cover safety, and the description covers behavior and output format.

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

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

Schema coverage is 100%, so baseline is 3. The description adds default and max values for 'max_links', and restates the purpose of 'url', providing extra clarity for agents.

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: generating a production-ready llms.txt file for any URL. It includes the specific output format and target AI crawlers, distinguishing it from siblings like 'scan_competitor_ai_presence'.

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 (indexing a client's site, drafting for own project, auditing competitor visibility). It does not explicitly exclude scenarios, but the context is clear enough for most agents.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds return field details and the default active filter, 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?

The description is two sentences, front-loaded with purpose, and every sentence provides value with no wasted words.

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

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

Given the annotations, schema, and context signals, the description covers all essential aspects: purpose, usage, behavior, and return fields. No output schema needed as fields are listed.

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

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

The only parameter 'include_inactive' is fully described in the schema. The description does not add extra meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'list' and the resource 'the caller's active subscriptions', and lists return fields. It distinguishes itself from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description explicitly says when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' It implies a context but does not include exclusions or 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 this is not read-only, not idempotent, not destructive. Description adds that feedback is sent to the team, read daily, and affects roadmap. 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?

Concise, front-loaded with main purpose, every sentence adds value. Uses bullet points in plain text (though schema has enum). Efficient and well-structured.

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

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

For a one-way feedback tool with no output schema, the description covers purpose, usage, constraints, and processing. No gaps given the tool's simplicity.

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

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

Schema coverage is 100%. Description adds value by repeating enum meanings, specifying that context is optional and structured, and providing guidance on message length (1-2 sentences, 2000 chars max) and specificity. Goes beyond 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 is for sending feedback about broken, missing, or needed items. It enumerates specific categories (bug, feature, data_gap, praise) and distinguishes from siblings like ask_pipeworx by specifying it's for reporting issues, not asking questions.

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

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

Explicitly tells when to use each feedback type, instructs not to paste end-user prompts, and notes rate limits (5/day) and that it's free with no quota impact. Provides clear context for appropriate use.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. Description adds value by specifying data source (CF analytics-engine), no PII, and caching behavior (5min-1h). 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?

Single paragraph, front-loaded with main action, followed by bulleted use cases and data notes. Efficient but could benefit from more explicit structuring (e.g., bullet points) for readability.

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

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

For a simple read-only tool with one optional parameter and rich annotations, the description covers purpose, use cases, data origin, caching, and parameter semantics. It is complete enough for an agent to decide invocation without missing critical details.

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 enum descriptions. The tool description adds extra context about window selection (short vs. long windows) beyond the schema, helping agents choose appropriately.

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

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

Clearly states it returns 'top tools, top packs, and total call volume' from other agents, with a specific verb 'calling on' and resource 'Pipeworx'. Distinguished from siblings by focusing on aggregated trending data.

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

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

Lists three specific use cases (discovering hot data sources, confirming canonical tool, checking alignment). Provides context on caching and window semantics but does not explicitly mention when not to use or compare to sibling tools like 'top10' or 'discover_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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) already indicate safety. The description adds extensive behavioral details: required parameter modes, partition checks, Jaccard similarity filter, placeholder filter, fill check against live CLOB depth, and trading guidance. 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 front-loaded requirement, then mode explanations, details (semantic anchor, partition filter, fill check), and response format. Somewhat lengthy but every sentence adds value. Slight redundancy in explaining fill check could be streamlined.

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

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

No output schema, so the description fully explains return values (opportunities[], partition_check) and includes fill check, custom sizing reference, and edge cases (placeholder slugs, similarity thresholds). Complete for a complex multi-mode 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%, baseline 3. The description adds significant meaning: explains event mode walks child markets and checks ordering, topic mode searches and flattens markets, provides example slugs/seed questions, and describes response fields. Greatly augments 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 precisely states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It clearly distinguishes two modes (event and topic) with examples, and stands out from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

It explicitly requires one of `event` or `topic`, warns that no args fails, recommends event for specific markets and topic for cross-event scanning, and explains cross-event catches patterns single-event misses. Does not explicitly list when not to use or compare with sibling tools, but context is clear.

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

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

The description provides extensive behavioral detail far beyond annotations: model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), edge calculation logic, Kelly sizing, caching (1h at KV level), and diagnostic fields. Transparency is excellent and adds significant context.

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

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

The description is thorough but verbose. It front-loads the main purpose and segments, but sections on model families and parameter details are lengthy. While every sentence adds value, the overall length could be trimmed for quicker parsing without losing essential information.

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

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

Given nine parameters, rich response structure, and no output schema, the description comprehensively covers response fields (edge_pp_net, kelly_fraction, liquidity, spread, move warning), diagnostics, and the Fed note. It leaves no significant gaps for an agent to understand the tool's behavior and output.

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

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

Schema coverage is 100%, and the description enriches each parameter with practical context: e.g., slippage_pp notes Polymarket's zero fees but typical 20-50bp spread; min_partition_leg_kelly explains its unique application; category_filter clarifies comma-separated values. This goes well beyond the schema alone.

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

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

The description clearly states the tool's core purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also specifies the three output segments and distinguishes this tool from siblings by focusing on edge detection.

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

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

The description is built for the use case 'what should I bet on today' and explains tradeable-edge knobs and parameter adjustments. However, it lacks explicit guidance on when NOT to use this tool or direct comparisons to sibling tools like polymarket_arbitrage.

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 details the response structure (tracked[], expired[], snapshot_dates[]) and explains that decay numbers are computed from daily closes of edge_pp_net (not intraday) and that snapshots are written on cache-miss, implying gaps. Annotations already indicate read-only, open-world, idempotent, non-destructive; the description adds significant behavioral context without contradiction.

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

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

The description is a single dense paragraph but is well-structured: it starts with the core question, then explains the response fields, and ends with limitations. Every sentence adds value. Could be broken into sections for easier parsing, but overall it is 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?

Given the tool's complexity (historical edge analysis, decay computation), the description is thorough. It explains the concept of edge persistence, the response structure in detail, and the limitations (TTL, snapshot timing). No output schema exists, but the description compensates by listing all fields. Annotations cover safety, so 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?

The input schema already covers both parameters (days and window) with descriptions and defaults. The description repeats the defaults (14 for days, '1wk' for window) but does not add significant meaning beyond what the schema provides. Schema coverage is 100%, 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's purpose: providing edge persistence and decay telemetry from daily polymarket_edges snapshots. It answers a specific question about edge age and shrinking. While it distinguishes itself from a generic data source (polymarket_edges), it could more explicitly contrast with sibling tools like polymarket_arbitrage or polymarket_fill_risk.

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

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

The description explains when to use the tool (to understand edge persistence and whether it's decaying) and provides a rationale for why a fresh edge differs from an old one. It also notes limitations (60-day TTL, snapshot start time) but does not explicitly state when not to use it or suggest alternative tools for different contexts.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it details the tool's operation ('walks the ladder'), outputs (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.), and warns about risks like forced directional risk and thin legs. 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 comprehensive but somewhat lengthy, covering modes, parameters, outputs, and warnings. It is well-structured with capitalized mode headers and bulleted output lists, making it scannable. However, some details (e.g., specific output field names) could be omitted or referenced to an output schema if one existed. Still, the complexity warrants length.

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

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

Given the tool's complexity (two modes, 4 parameters, no output schema), the description is remarkably complete. It explains input requirements, output fields for both modes, risk warnings, and usage context. The absence of an output schema makes the detailed description essential, and it fulfills that need 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 description coverage is 100%, but the description adds significant meaning beyond the schema. It clarifies the 'side' parameter's default behavior in basket mode (auto from partition sum) and the dual interpretation of 'size_usd' (max spend vs target proceeds in single-market; settlement notional in basket). This helps agents understand usage nuances.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool before those.

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

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

The description provides explicit usage context: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround on thin books is not capturable) and what happens if not used (partial fills convert arb into unhedged position). It lacks explicit 'when not to use' but is sufficiently clear.

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

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

The description goes well beyond annotations by detailing compatibility warnings, temporal alignment checks, and skipped cross-type/subtype counters. It fully discloses when spreads are meaningless (shape mismatches, temporal gaps) and explains the internal matching logic.

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

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

The description is relatively long but well-structured with clear sections and front-loaded purpose. Every sentence contributes essential detail for the tool's complexity, though minor redundancy exists (e.g., repeating the compatibility warning caveat).

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

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

Given no output schema, the description adequately explains the response structure (leg prices, spreads, safety fields) and all edge cases. It covers prerequisites, limitations, and the meaning of key fields, but could provide a more explicit example of the output JSON format.

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

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

With 100% schema coverage, the description still adds value by explaining the two modes, the list of topic shortcuts, and how explicit parameters override the topic. This provides practical usage context beyond the schema's parameter descriptions.

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

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

The description clearly states it computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes the tool from siblings by emphasizing its dual-venue comparison and specific modes, making it easy to understand its unique value.

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 two modes (topic and explicit) and provides context on when the tool is meaningful (e.g., when events are aligned and matched). It warns that most pre-mapped topics are not tradeable, giving clear usage guidance, though it does not explicitly compare to sibling tools like polymarket_arbitrage.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds scope (scoped to user identifier) and relationship to other memory tools, providing extra 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 concise sentences covering purpose, usage, and scope. No unnecessary words; front-loaded with key 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?

Tool is simple with one optional parameter. Description covers retrieval, listing, scoping, and pairing. No output schema, but return values are implied. Minor gap: exact return format not described.

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

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

Schema fully describes the key parameter (omit to list). Description reinforces this with examples. No additional semantics added beyond 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?

Clearly states the tool retrieves a value or lists keys, referencing the sibling 'remember' tool. Distinguishes its purpose from 'forget' and other siblings.

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

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

Explicitly says when to use (look up context stored earlier) and pairs with remember/forget. Does not explicitly state when not to use, but context is clear.

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

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

The description claims that setting mark_read:true flags returned events as read and affects subsequent calls, implying a server-side state change. This contradicts the readOnlyHint annotation (true) which indicates no data modification. Per scoring rules, a contradiction with annotations results in a score of 1.

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

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

The description is four sentences, starting with the primary purpose, then detailing returned fields, filter options, side effects, and an alternative access method. Every sentence adds information without redundancy or waste.

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

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

Despite the contradiction, the description covers the tool's functionality well, including return format, parameter usage, side effects, and alternative access. With no output schema and all parameters optional, the description provides sufficient context for correct invocation, leaving no major gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing examples (e.g., type 'sec_8k'), clarifying 'since' as an ISO timestamp, and explaining the behavioral effect of 'mark_read'. This goes beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifies the returned fields (source, citation_uri, raw payload), and includes filter examples. It effectively communicates the tool's purpose and distinguishes its scope from siblings by mentioning the REST endpoint alternative.

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

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

The description explains parameter usage (filter by type, since, mark_read) and notes that polling works fine. It also provides an alternative access method (GET endpoint). However, it does not explicitly state when to use this tool versus other sibling tools like list_subscriptions, so it lacks comprehensive tool selection guidance.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) already indicate safety. The description adds significant behavioral detail: fan-out to SEC EDGAR, GDELT with GNews fallback, USPTO soft-fail, and returns structured changes with citation URIs. 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 informative and well-structured: starts with examples, explains sources, parameters, return, and sibling comparison. Every sentence adds value, though slightly longer than minimal. Still highly effective.

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

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

Given no output schema, the description explicitly states return structure (changes[] grouped by source, total_changes, citation URIs). It covers source behavior, fallback, and limitations. Complete for a complex aggregator tool.

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

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

Schema coverage is 100%, so baseline 3. Description adds meaning: explains `since` accepts ISO date or relative shorthand with examples, suggests '30d' for monitoring; clarifies `value` as ticker or CIK; notes `type` only supports 'company'. This adds useful usage context 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 starts with concrete user queries, then states 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly distinguishes itself from sibling 'entity_profile' (static profile). This meets the criteria of specific verb+resource and sibling differentiation.

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

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

The description provides explicit guidance: lists example queries, explains the parallel fan-out to multiple sources, describes fallback behavior (GDELT→GNews), and contrasts with 'entity_profile' when static profile is needed. It also clarifies the `since` parameter usage. This fully addresses 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 indicate idempotent and non-destructive behavior. The description adds useful context: key-value scoping, persistent memory for authenticated users, and 24-hour retention for anonymous sessions. No contradiction found.

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?

Every sentence serves a purpose: purpose, usage, details. No fluff. Front-loaded with the core 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?

Given the simplicity of the tool (no output schema), the description fully covers scope, persistence, and relationship to siblings. 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% and the description reinforces the parameter meanings (key-value pair, scoped by identifier). Adds examples of what values to store, enhancing understanding beyond the schema.

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

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

The description clearly states the verb 'Save' and the resource 'data' with the purpose of reusing later. It distinguishes itself from sibling tools 'recall' and 'forget' by naming them explicitly.

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') and mentions alternatives ('Pair with recall to retrieve later, forget to delete').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about internal cascading lookups and replacing manual steps, enhancing transparency without contradicting annotations.

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

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

The description is well-structured with examples and bullet points, front-loading the purpose. While slightly lengthy, every sentence adds value and it avoids 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 both entity types' inputs and outputs, aligning with the tool's complexity. Context signals show high schema coverage and no nested objects, leaving 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%, and the description adds valuable meaning by providing concrete examples of values (ticker, CIK, name) and explaining the output for each type, which goes beyond the schema's basic descriptions.

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

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

The description explicitly states the tool resolves names to canonical identifiers, provides clear examples ('What's the ticker for...'), and distinguishes from siblings by saying 'Use FIRST whenever you have a name but need an ID.' It also lists specific supported types and what they return.

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

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

The description gives clear when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and explains it replaces multiple lookups. It does not explicitly say when not to use it, but the context of sibling tools implies alternatives for different purposes.

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

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

The description discloses that the tool internally calls 'ai_visibility_check' for each entity, ranks results, and returns a ranked list. This adds value beyond annotations (readOnlyHint, idempotentHint, etc.) by revealing the compound nature. It also mentions API key handling for Anthropic. Minor gap: doesn't discuss potential rate limits or the number of calls made.

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 parenthetical example, all front-loaded with the core action. Every sentence is purposeful, no wasted words. It is concise yet highly 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 the tool's complexity (4 params, no output schema), the description adequately covers all aspects: what it does, how it works, parameter meanings, and output format (ranked list with score, confidence, signal density). It is complete and self-contained.

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

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

With 100% schema coverage, baseline is 3. The description adds substantial meaning: 'First entry treated as the subject for narrative,' explains 'context' as disambiguating names, and clarifies 'models' default behavior and '_apiKey' usage. These details significantly enrich the schema, justifying a 5.

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 action: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb 'compare' and the resource 'AI visibility of entities,' and distinguishes from siblings like 'ai_visibility_check' (single entity) by emphasizing multi-entity comparison.

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

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

The description provides explicit context: 'Useful for competitive AI-marketing audits' with a concrete example. It implies usage when comparing multiple entities, but does not explicitly exclude single-entity scenarios (handled by sibling 'ai_visibility_check'). The guidance is clear but lacks explicit 'when not to use' instructions.

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

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

Adds rich context beyond annotations: fans out across two services, returns summary block with specific fields, handles partial failures gracefully (bundlephobia timeout, sources_failed list). Annotations already indicate read-only, idempotent, non-destructive, and open-world.

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 information-dense but well-structured, starting with the core composite purpose and then expanding on usage, returns, and edge cases. It earns its length by providing necessary detail.

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

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

Given the tool's complexity (multiple data sources, return structure, partial failures), the description covers all critical aspects without an output schema. It explains the summary block fields, advisory details, links, and alternative versions.

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 parameter descriptions. The description reinforces that scoped packages are accepted and version defaults to latest, but adds no new semantic info 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 composite check for npm packages, covering safety, popularity, and size. It distinguishes from siblings by specifying the NPM ecosystem focus and referencing deps.dev and bundlephobia.

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') and what not to use (PyPI/Maven/Cargo/Go go to deps.dev:version directly). This provides clear guidance on alternatives.

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

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

Discloses key behavioral traits beyond annotations: uses BGE-base-en embeddings + cosine over 500-char windows, 200K char cap with truncation flag, and returns offsets. 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?

Single paragraph is dense but front-loaded with purpose. Could be more scannable with bullet points, but 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?

Despite no output schema, the description explains return format (passages with offsets and similarity scores) and pairing with ask_pipeworx_grounded. All necessary context for an agent is present.

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 adequate descriptions. The description adds value by providing examples for the 'query' parameter and noting the 200K char limit for 'text'.

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 'Semantic search INSIDE a fetched record' and distinguishes from siblings by pairing with ask_pipeworx_grounded and contrasting with the gateway fetch. The verb+resource is specific and unique.

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

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

Explicitly tells when to use: 'Use when the record is too big to cram into the prompt' and mentions an alternative (ask_pipeworx_grounded). Provides clear context and exclusions.

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

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

Annotations indicate non-readOnly, idempotent, non-destructive. The description adds details: returns subscription id, requires OAuth, SMS cap, webhook auto-disable. It complements annotations without contradiction.

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

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

The description is a single dense paragraph that front-loads the purpose. It could be more structured (e.g., bullet points) but is efficient and readable.

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 explicitly states it returns the new subscription id. It covers all types, delivery channels, requirements, and edge cases (auto-disable). Very complete for a complex tool.

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

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

Schema coverage is 100%, but the description enriches all parameters: explains each type's params format, delivery channel details, verification, and limits. 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 verb 'Create' and the resource 'proactive monitoring subscription', and distinguishes it from siblings like list_subscriptions and unsubscribe. It provides specific purpose and outcome.

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

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

The description specifies when to use (creating a subscription), and outlines requirements (Pipeworx OAuth account). It doesn't explicitly mention alternatives but the sibling context covers them. The examples and constraints give good usage context.

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

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

Adds substantial context beyond annotations: describes output as live catalog-sourced example questions with exact tool and argument shapes. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description enhances transparency by detailing the dynamic, curated nature of the results and the onboarding purpose.

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 efficiently convey purpose, output details, and usage guidance. The first sentence front-loads common user queries, making it easy for an agent to recognize intent. No redundant or extraneous text. Every sentence serves a clear function.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is fully complete. It covers what the tool does, what it returns, how it can be parameterized, and when to invoke it. References meta-tools to provide broader context. No missing information for an agent to use this tool effectively.

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

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

The single optional parameter 'topic' is described in schema with a list of options and default behavior. The description enriches this by listing the full set of categories (company financials, drugs, etc.) that are not fully enumerated in schema, and explains that omitting topic yields a cross-category spread. This adds meaningful context beyond the schema, though schema coverage is 100%.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It uses specific verb 'suggest' and resource 'questions', and the title 'What Can I Ask Pipeworx?' further clarifies purpose. Distinguishes from siblings like 'discover_tools' by focusing on onboarding and learning capabilities.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also provides guidance on optional parameter usage: call with no arguments for full spread, or pass topic to focus. This gives clear when-to-use and how-to-use instructions.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds value by detailing the output structure (category id, name, summary, URL) and listing the available lists, which helps the agent understand what to expect.

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

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

The description is two sentences, front-loading purpose and use cases, then listing options. It is efficient with no wasted words.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers purpose, use cases, output summary, and list options. It is complete for an agent to invoke correctly.

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

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

The schema has 100% coverage for the single parameter (list) with an enum and description. The description reiterates the list options but doesn't add significant new meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states it provides an OWASP Top 10 list with categories and details, including specific use cases like awareness, mapping findings, and threat modeling. It distinguishes itself from sibling tools by specifying its unique content (OWASP Top 10 lists for web, API, LLM, mobile).

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

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

The description explicitly states when to use it: for awareness, mapping a finding to a category, or LLM-app threat modeling. It provides context but does not mention when not to use or suggest alternatives, though given the simple nature and lack of similar siblings, this 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?

Description adds critical behavioral details beyond annotations: deactivation instead of deletion, and preservation of historical events in 'recent_alerts'. No contradiction.

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

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

Two concise sentences, front-loaded with key action and ownership, no waste.

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

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

No output schema, but description explains effect and historical availability. Ownership and deactivation are well covered. Slight gap: no return value description.

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

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

Schema coverage is 100% and already describes the 'id' parameter. The description adds minimal extra beyond 'Cancel a subscription by id.'

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 verb 'Cancel' and resource 'subscription by id' are precise. It clearly distinguishes from sibling tools 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?

Ownership enforcement is explicitly stated, guiding when the tool can be used. The deactivation vs deletion explanation helps compare with other tools like 'recent_alerts'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds behavioral context: returns a verdict with types, extracted structure, actual value with citation, and percent delta, and that it replaces 4-6 sequential calls. No contradictions.

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

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

The description is well-structured, front-loading examples of user intents. It is detailed but not verbose; every sentence adds value. Could be slightly shorter, but the richness justifies the length.

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

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

Given no output schema, the description thoroughly explains the return format (verdict types, structure, citation, delta), the domain (company-financial), and data sources. It is complete for the tool's purpose.

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

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

Schema covers 100% of the single parameter with a description. The tool description adds natural-language examples and format guidance ('e.g., "Apple's FY2024 revenue was $400 billion"'), which enriches the schema's minimal description.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, specifically for company-financial claims. It distinguishes from siblings by noting it replaces multiple sequential calls, and provides concrete examples of user intents.

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 specifies the domain (company-financial claims) and data sources. Though it doesn't explicitly say when not to use, the domain constraint is clear enough.

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