nouel

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the return format (per-model score, confidence, signals, raw_response) and explaining that _apiKey is passed directly to Anthropic, which is beyond the annotation information.

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, well-structured: first sentence states overall purpose, second covers model options, third describes return format, fourth lists use cases. Every sentence is informative without redundancy.

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

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

Given 4 parameters and no output schema, the description adequately covers the tool's functionality and return format. It could elaborate on the scoring mechanism or what 'signals' means, but the current level is sufficient for an AI audit 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?

With 100% schema coverage, baseline is 3. The description adds extra meaning by explaining the default model, the need for _apiKey to probe Anthropic, and the purpose of context parameter for disambiguation, thus surpassing the baseline.

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

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

The description clearly states the verb 'probe', the resource 'LLMs', and the output 'score visibility (0-100) per model'. It differentiates by specifying applicable use cases like AI-marketing audits, pre-launch brand checks, and competitive monitoring, effectively 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 explains when to use the tool (AI visibility checks) and provides context for parameter usage (default model vs. Anthropic with key). It does not explicitly state when not to use or compare to alternatives, but the mention of use cases gives sufficient 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context by explaining that the tool routes to 3,745 tools across 884 sources, fills arguments, and returns structured answers with pipeworx:// citation URIs. It does not contradict annotations. However, it could mention potential latency or rate limits, but overall it provides sufficient transparency.

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

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

The description is well-structured: it opens with a strong directive, lists source types, explains functionality, and provides concrete examples. Every sentence adds unique value without redundancy. It is concise given the tool's complexity and the need to differentiate from web search.

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 required parameter and no output schema, the description is remarkably complete. It covers the tool's scope, behavior, usage triggers, and output format (structured answers with citations). Annotations confirm read-only and idempotent behavior. No obvious gaps remain for effective agent usage.

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

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

Schema coverage is 100% with detailed descriptions for all six aliases. The description adds value by explaining that the tool accepts natural language questions and gives examples with trigger words. It reinforces the schema's meaning and provides practical guidance on how to phrase queries, which goes beyond the schema's aliases.

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

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

The description clearly states that this tool routes questions to a vast set of verified sources for authoritative structured data with citations. It specifies domains like SEC filings, FDA data, economic statistics, etc., and explicitly contrasts with web search. The verb 'ask' with 'Pipeworx' is specific, and the description distinguishes it from generic web search, making its purpose unmistakable.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' for factual questions and provides concrete trigger phrases (e.g., 'what is', 'look up', 'get the latest') and examples. It clearly indicates when to use this tool over web search, which is the primary alternative. The guidance is comprehensive and actionable.

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

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

Description adds substantial behavioral context beyond annotations: explains multi-step routing, extraction-only constraint, return structure with evidence/confidence/refusal reasons, and cost trade-off (one extra LLM call). 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?

Description is detailed but front-loaded with key purpose and behavior. Every sentence serves a purpose, though slightly verbose. Could be tightened slightly without losing clarity.

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

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

Given the tool's complexity (6 params, no output schema, but rich annotations), the description covers all essential aspects: purpose, behavior, return format, refusal reasons, usage guidance, and sibling comparison. Nothing critical is missing.

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

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

Schema coverage is 100% with all parameters documented, including aliases for question. Description does not add meaningful semantic information beyond what 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?

Description clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads, distinguishing it from ask_pipeworx. It states the exact behavior: routes to appropriate tool, extracts answer only from tool result, and returns structured output with explicit refusal reasons.

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

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

Explicitly states when to use (when quoting/citing/acting on answers, high-stakes domains) and when not to use (prefer ask_pipeworx for casual lookups). 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?

The description extensively details behavioral traits beyond annotations: low-confidence short-circuit, closed market handling, wide-spread tradeability warning, resolution-rule risk, parent event extraction, and news fallback. Annotations already convey safety and idempotency; description adds rich operational 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 comprehensive but overly long, covering many details that could be summarized or placed elsewhere. It front-loads purpose but then goes into extensive examples and edge cases, making it less concise. Adequate structure but wordy.

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 classifiers, fan-out sources, response shapes), the description covers all essential aspects: resolver contract, parent event, news fields, safety mechanisms, and resolution-rule risk. No output schema exists, so the description fully explains return values, making it complete.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds value by explaining input flexibility (slug, URL, or text) and the effect of depth (quick vs thorough evidence sources) and include_raw (response size). This supplements the schema well.

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

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

The description clearly states the tool researches a Polymarket bet by pulling relevant Pipeworx data, specifying input types and output. It distinguishes from sibling tools like polymarket_edges by focusing on single-market research with evidence packets.

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

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

The description explicitly lists use cases (should I bet, what does data say, is there edge). It provides context but lacks explicit alternatives or when-not-to-use statements. The comprehensive safety and resolution advice further guides 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?

Discloses data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs), handling of off-calendar fiscal years, sorted results, and citation URIs. All annotations are consistent; 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, starting with query examples, then behavior, then data sources. Slightly verbose but every sentence adds value. Could trim minor redundancy.

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

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

Covers all aspects: input, behavior for both entity types, edge cases (off-calendar fiscal years), output format (paired data with citation URIs). Good given no output schema and 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 already describes both parameters (type, values). Description adds meaning: explains what data each type retrieves and the format for values (tickers/CIKs vs drug names). This enhances understanding beyond the schema.

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

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

Description states the tool does side-by-side comparison of 2-5 companies or drugs. It uses specific verbs like 'compare' and 'rank', and distinguishes between entity types. Examples like 'which is bigger' clarify intent.

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 advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear guidance on when to use this tool. No exclusions, but the preference is strong.

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, openWorldHint=true, destructiveHint=false. Description adds behavioral details: decomposition, parallel routing, extraction with verbatim evidence, confidence, source, fetched_at, stable citation, and explicit gaps[]. Also mentions 15-60s latency. 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?

Description is dense with useful information but somewhat long. Front-loaded with key purpose, but a few sentences could be trimmed without loss. Still well-structured.

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

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

Given the tool's complexity (3,745 tools, 884 sources), the description covers all critical facets: purpose, usage, behavior, parameters, prerequisites, performance, and output structure. No output schema exists, but description details the return packet.

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

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

Schema covers both parameters (100% coverage). Description adds meaning: depth enum values are explained (quick=3, standard=5, thorough=8) and that thorough requires paid plan. Question param: 'Broad/multi-part is fine — decomposition is the point.'

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 'Grounded multi-source research in ONE call', explaining decomposition, parallel routing, and extraction of evidence. It distinguishes from sibling tool 'ask_pipeworx' by noting the latter is for single 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 states when to use this tool ('Use for broad or multi-part questions') and when to use an alternative ('use ask_pipeworx for single lookups'). Also mentions prerequisites: Pipeworx account, paid plan for 'thorough' depth.

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 that results include full schemas with examples and are callable immediately, no second lookup needed. No contradiction.

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

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

Front-loaded with core purpose, then details. Slightly long but every sentence adds value. Could trim some examples but overall 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?

No output schema, but description explains what is returned (names, descriptions, schemas, examples). Mentions 'top-N' but not pagination details. Sufficient for a discovery tool.

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

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

Schema coverage is 100%, so baseline 3. Description adds that query accepts natural language and aliases, which schema already covers. Does not significantly extend beyond schema.

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

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

The description clearly states the tool finds tools by describing data/task, lists domains, and distinguishes from siblings (e.g., specific data tools vs. discovery). It uses specific verbs and resource.

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

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

Explicitly says 'Call this FIRST when you have many tools available' providing clear context. Lacks explicit when-not-to-use, but alternatives implied.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant detail: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), lists return fields, and mentions soft-fail for patents. 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 but slightly verbose. It front-loads purpose with examples and then details sources and returns. Structured well but could be trimmed slightly without losing clarity.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly covers return values (cik, filings, fundamentals, patents, news, LEI) and limitations (patents sunset, name unsupported). Completely explains what the tool does and returns.

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 meaning: explains type enum is limited to 'company', value can be ticker or zero-padded CIK, and names are not supported. Supplements schema effectively.

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 a full cross-source profile of a US public company. It uses specific verbs like 'profile' and 'research', lists example queries, and distinguishes from sibling tools like resolve_entity and compare_entities.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack lookups' when a holistic view is needed. Also advises using resolve_entity if only a name is available, and notes the patents API sunset. Clear when to use and when not.

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 destructiveHint=true, so description doesn't need to reiterate destructiveness. However, it could add details like what happens if the key doesn't exist or if deletion is irreversible. The description adds minimal behavioral info beyond annotations.

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

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

Two sentences with no filler. The action is front-loaded, and every sentence serves a purpose: stating the action and providing usage guidance.

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 single-parameter tool with no output schema, the description covers purpose, usage, and relationship to siblings adequately.

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 of 'key' is already clear in the input schema. The tool description does not add further semantic detail 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 uses a specific verb ('Delete') and resource ('memory by key'), clearly distinguishing it from siblings like 'remember' and 'recall' which store and retrieve respectively.

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 is stale, task done, clear sensitive data') and pairs with alternatives ('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 explains the process: fetches the page, extracts title/description/links, and emits standard llms.txt markdown. This adds behavioral detail beyond annotations, which already indicate safety.

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: purpose, process, use cases. No unnecessary words, well-structured for quick reading.

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 simple tool (2 params, no output schema), the description covers all needed aspects: what it does, how it works, output format, and practical uses.

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 both parameters have descriptions in the schema. The description does not add additional meaning, so baseline score applies.

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

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

The description states the verb 'generate' and the specific resource 'llms.txt file', and distinguishes it from sibling tools like ai_visibility_check by focusing on file generation rather than checking visibility.

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

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

The description lists three concrete use cases (client indexing, personal drafting, competitor auditing), providing clear context for when to use the tool, though it does not explicitly mention alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that it returns laureate names, categories, and citations, and that results can be filtered by category. This provides some context beyond annotations.

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

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

Two sentences clearly convey the tool's purpose and key details. No fluff, front-loaded.

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

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

For a simple query tool with two parameters and an output schema, the description covers what the tool does, what it returns, and the optional filter. It is complete and sufficient.

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

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

Schema coverage is 100%, but the description adds value by showcasing natural language category examples (e.g., 'Chemistry', 'Peace') alongside the formal codes, making it more user-friendly.

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 retrieves Nobel Prizes by year with optional category filtering, and mentions the return fields. It distinguishes itself from siblings like search_laureates by focusing on a specific year, but does not explicitly differentiate.

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?

No guidance on when to use this tool versus alternatives such as search_laureates. The description only states what it does, not when to prefer it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds the return field details and mentions the 'active subscriptions' default, which is consistent but does not significantly extend beyond the annotations.

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

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

The description is two sentences: the first states purpose and output, the second offers usage guidance. It is concise, well-structured, and front-loaded with 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 the simple nature of the tool (one optional boolean parameter, no output schema) and rich annotations, the description is complete enough. It covers purpose, output fields, and usage. Minor missing details like pagination are acceptable for this context.

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

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

Schema coverage is 100% and the lone parameter 'include_inactive' has a description in the schema. The tool description does not add extra meaning beyond that, so a score of 3 is appropriate.

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

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

The description clearly states the tool lists active subscriptions and details the return fields (id, type, params, timestamps, fire_count). This is a specific verb and resource, and it differentiates 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 advises using the tool to review subscriptions before adding more or to find an id to cancel, providing clear context for when to use it. It does not list exclusions, but the guidance is practical.

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

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

Annotations are all false, but description supplements with key behavioral traits: 'Rate-limited to 5 per identifier per day. Free; doesn't count against your tool-call quota.' It implies non-destructive, read-only consumption. No annotation contradiction.

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

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

Description is concise (3 sentences) yet packs essential information: purpose, usage triggers, formatting rules, and constraints. Every sentence adds value; no wasted words. Front-loaded with clear purpose.

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

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

Given the tool has 3 parameters (2 required), no output schema, and moderate complexity, the description covers all critical aspects: purpose, when to use, how to format, rate limits, and quota behavior. An agent can correctly invoke this tool without additional context.

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

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

Schema coverage is 100% with descriptions, so baseline is 3. Description adds value by expanding on parameter usage: for 'type' it reiterates enum meanings concisely, for 'message' it gives formatting tips and max length, and for 'context' it clarifies it's optional. This extra guidance justifies a 4.

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

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

Description explicitly states 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly defines the tool as a feedback mechanism, distinct from sibling tools which are research/query tools. The verb 'tell' and resource 'Pipeworx team' with specific feedback types (bug, feature, etc.) make purpose unambiguous.

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

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

Description provides detailed when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also includes formatting instructions ('don't paste the end-user's prompt, describe in terms of Pipeworx tools/packs') and constraints (rate limit, quota).

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

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

The description adds value beyond annotations: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false; description complements 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 front-loaded with the core functionality, followed by a bullet-like list of use cases and then additional context. Every sentence earns its place, and the length is appropriate for a simple list-style tool.

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

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

Given the simple input (one optional parameter, no output schema), the description covers return structure, data source, privacy, caching duration, and use cases. It is complete for an agent to understand invocation and expected results.

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

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

Schema coverage is 100% with a single parameter 'window'. The description enriches the enum values by explaining: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds context beyond the schema's 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 returns top tools, top packs, and total call volume over a recent window (24h, 7d, 30d). It uses a specific verb-resource pairing and distinguishes itself from sibling tools like 'ask_pipeworx' or 'discover_tools'.

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

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

It explicitly lists three use cases (discovering hot data sources, confirming popular tools, seeing alignment with agent needs). It mentions caching behavior and window semantics. However, it does not explicitly state when not to use it or directly compare to siblings beyond the context.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds substantial behavioral context: semantic anchor (Jaccard similarity ≥0.30), partition filter (drops placeholder slugs >20%), fill check against live CLOB depth. No contradiction with annotations.

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

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

The description is detailed and well-structured, starting with the requirement, then explaining both modes, followed by semantic details, partition filter, response, and fill check. Slightly lengthy but each section adds value.

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

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

Covers inputs, modes, output fields (opportunities[], partition_check, fill_check), and edge cases (similarity filter, placeholders). Lacks explicit full output schema definitions for all fields, but adequate given 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?

Input schema provides descriptions for both parameters (event and topic) with 100% coverage. The description adds examples and explains the difference between single-event and cross-event modes, 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 that the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It explains two modes (event and topic) and distinguishes from sibling tools like 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?

Explicitly requires one of event or topic, warns that calling with no args fails, recommends event for specific markets and topic for cross-event scanning, and advises not to trade when realizable_edge_pp ≤ 0. Also suggests using polymarket_fill_risk for custom sizing.

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

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

Annotations indicate readOnlyHint and idempotentHint. The description adds extensive behavioral context: caching strategy, detailed model family mechanics (e.g., lognormal barrier, GDELT ratio, partition arbs with corrections), edge calculations, Kelly sizing caps, and 24h-move warnings. No contradictions with annotations.

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

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

The description is very long and dense, with multiple paragraphs. While logically structured, it could be more concise to avoid overwhelming the agent. Some details could be streamlined 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?

Extremely complete given no output schema. Describes response structure (by_segment, diagnostics, Fed notes), caching keyed on all knobs, filter skip reasons, and detailed edge calculations. Addresses edge cases like Fed market exclusion and partition arb 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?

All 9 parameters have schema descriptions (100% coverage), so baseline is 3. The description adds value by explaining tradeable-edge knobs (min_liquidity, max_spread_pp) and min_partition_leg_kelly in detail, providing context beyond simple parameter names.

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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. Differentiates from sibling tools like polymarket_arbitrage and polymarket_kalshi_spread by focusing on edge detection using proprietary signals.

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 'Built for what should I bet on today' and describes how agents can discover opportunities without paging hundreds of markets. Provides guidance on tuning knobs but does not explicitly state when not to use this tool or mention 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 declare read-only, open-world, idempotent, non-destructive. Description adds that snapshots are written on cache-miss, so gaps mean no scan that day, and decay is based on daily closes, not intraday. No contradictions, and additional context enhances transparency.

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

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

The description is front-loaded with purpose and response structure. While lengthy, every sentence contributes value, explaining output fields and limits. Slightly verbose but well-organized.

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

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

Despite no output schema, the description thoroughly explains the response: tracked array with time-series, first_seen, trend, decay; expired array with lifespan; snapshot_dates. Also covers calculation basis and limitations. Complete for a complex analytics tool.

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

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

Schema coverage is 100% with descriptions for both parameters. Description reinforces defaults (days: 14, max 30; window: '1wk') and adds the concept of 'snapshot family'. This adds value beyond the schema.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering how long an edge has existed and if it is shrinking. It distinguishes itself from sibling polymarket_edges by focusing on time-series analysis rather than raw edge 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?

The description gives context with the example of a fresh vs. 3-week-old edge, implying when to use this tool for time-decay insights. It also notes limits like the 60-day TTL and that gaps indicate days without scanning. No explicit exclusion of alternatives, but the guidance is clear.

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

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

Annotations provide readOnlyHint, idempotentHint, etc., reducing burden. Description adds behavioral context beyond annotations: lists specific return fields (top_of_book, vwap_fill_price, verdict, etc.), explains the risk of partial basket fills, and warns about forced directional risk. This goes beyond what annotations convey.

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 lengthy but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). It front-loads the core purpose and progressively adds details. Every sentence serves a purpose, given the complexity of two modes. Minor redundancy could be trimmed, but overall efficient.

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

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

Given no output schema, description lists all return fields and their meanings, covers both modes, defaults, constraints, and usage context. It addresses edge cases like thin books and forced directional risk. Could mention error handling (e.g., insufficient liquidity), but still highly complete.

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

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

Schema has 100% parameter coverage with detailed descriptions. Description adds extra meaning by explaining default behaviors (e.g., side auto-detection for baskets), clarifying size_usd interpretation in each mode, and providing clamping range. This enriches the schema without redundancy.

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

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

Description clearly states it performs 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market vs basket). It explicitly positions itself as a pre-trade risk check for sibling tools like polymarket_arbitrage and polymarket_edges, making purpose and differentiation unmistakable.

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

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

Description explicitly states when to use this tool: 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains consequences of not using it (partial fills, unhedged positions), providing clear context and exclusion 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is clear. The description adds valuable behavioral context: it explains compatibility warnings, temporal alignment constraints, and skipped cross-type/subtype counters, which go beyond what annotations provide.

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

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

The description is well-structured: it starts with the main purpose, then modes, response format, and safety fields. It is dense but not excessively long. A slightly more concise presentation could improve readability, but it remains effective.

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

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

Despite no output schema, the description thoroughly explains the response structure: venues leg-by-leg prices, matched spread, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It also covers edge cases like non-equivalent bet shapes, making the tool's behavior fully transparent.

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

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

Schema coverage is 100% but description adds significant value: it lists the 10 topic shortcuts, explains that explicit tickers override the topic-mapped side, and provides examples (e.g., 'fed' or 'kalshi_event_ticker'). This helps the agent understand the two modes and how to use them.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It differentiates from siblings like polymarket_arbitrage by specifying 'cross-venue' and mentions two distinct modes (topic shortcuts and explicit tickers).

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 each mode and includes cautionary notes about pre-mapped topics not always being tradeable. However, it does not explicitly compare to sibling tools like polymarket_arbitrage or polymarket_edges, leaving some ambiguity about when to prefer this over alternatives.

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

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

Annotations already mark it as read-only and idempotent. Description adds scoping to identifier (anonymous IP, BYO key hash, account ID) and behavior when omitting key. No contradictions.

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

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

Two efficient sentences that front-load the primary action and key behaviors. No extraneous information.

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

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

For a simple read tool with no output schema, the description covers purpose, usage, scoping, and pairing. Could mention return format briefly, but not essential.

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

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

Schema has 100% coverage for the single optional 'key' parameter. Description adds the critical behavior that omitting the key lists all keys, which goes beyond the schema description.

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

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

Description clearly states the tool retrieves a saved value or lists all keys, with specific verb 'retrieve' or 'list', and resource is context stored via remember. Distinguishes from siblings like remember and forget.

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

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

Provides explicit use cases such as looking up user's target ticker, address, or research notes, and notes pairing with remember/forget. 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by explaining the effect of mark_read (flags events read for next call) and the return format. 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?

All three sentences are information-dense and front-loaded. Every sentence provides distinct value—purpose, fields, filters, side effects, and alternative access. No wasted text.

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 5 optional parameters, no output schema, and rich annotations, the description covers main return fields, filtering, mark_read behavior, and alternative access. It does not mention unread_only or error handling, but overall it is sufficiently complete for agent invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning for 'type' with an example ('sec_8k'), explains 'since' as ISO timestamp, and elaborates on 'mark_read' side effects. However, 'limit' and 'unread_only' are not mentioned; overall, it improves 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?

Clearly states 'Pull fired events from your subscription feed' and lists key fields (source, citation_uri, payload). While no explicit sibling differentiation, the description is specific enough to distinguish from other tools in the list.

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 guidance on filtering by type and since, using mark_read, and notes that polling works and the same feed is available via a GET endpoint. Does not explicitly state when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral details: fans out to three sources (SEC EDGAR, GDELT→GNews fallback, USPTO), explains the fallback mechanism, notes USPTO soft-fails until reactivated, and describes the return structure (changes[] grouped by source + total_changes + pipeworx:// URIs). No contradiction with annotations.

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

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

The description is two paragraphs with clear front-loading: first sentence gives high-level purpose and examples, then details sources and behavior. Every sentence is essential, no filler. It efficiently conveys complex multi-source behavior without unnecessary length.

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

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

Despite no output schema, the description explains the return format (structured changes[] grouped by source + total_changes + citation URIs). It covers sources, fallback, parameter formats, and the USPTO caveat. Given the tool's complexity, the description is fully sufficient for correct agent invocation.

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

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

Schema coverage is 100%, but the description adds valuable usage semantics: explains that `since` accepts ISO dates or relative shorthand, provides examples and a recommended default ('30d' or '1m'), clarifies that `value` accepts ticker or CIK, and notes that `type` only supports 'company'. This goes beyond the schema definitions.

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

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

The description opens with concrete query examples ("What's new with X", "latest on Y") and explicitly states it's a change feed for a company in a time window, making the purpose unmistakable. It also distinguishes itself from the sibling tool entity_profile by directing users to that tool for static profiles regardless of window.

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

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

The description provides explicit when-to-use guidance through example queries and a clear alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains fallback behavior for news and parameter usage (e.g., 'Use "30d" or "1m" for typical monitoring'). However, it doesn't explicitly state when not to use this tool.

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

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

Discloses scope and persistence: 'scoped by your identifier. Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' Annotations already indicate idempotentHint=true, but the description adds valuable context beyond structured fields, with 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 efficient: purpose, when-to-use, technical details (scope/persistence), and pairing. Each sentence earns its place, though slightly verbose for a simple tool.

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

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

Given the tool's simplicity (2 params, no output schema, straightforward behavior), the description fully covers purpose, usage, behavior, and relationships with siblings. No gaps remain.

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

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

Schema description coverage is 100%, with both parameters well-described in the schema ('key' with examples, 'value' as free text). The description adds no extra parameter details, so meets the baseline.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' and specifies the resource as memory key-value pairs. It distinguishes from sibling tools like recall and forget by explicitly pairing with them.

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

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

Provides explicit guidance on when to use: 'when you discover something worth carrying forward' and pairs with recall and forget for retrieval and deletion. This helps the agent decide to use this tool over alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral context: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups.' It also details what is returned for each type, including citation URIs, going well beyond the annotations.

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

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

The description is dense yet well-structured, starting with example queries, then stating when to use, then detailing each type. Every sentence is informative with no wasted words. It fits within a few lines but conveys all necessary information efficiently.

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

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

Despite lacking an output schema, the description thoroughly explains the return values for both entity types, including specific fields (ticker, CIK, company name, citation URI for company; RxCUI, ingredient, brand, citation for drug). It covers input, behavior, and output completely for a two-parameter lookup tool.

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

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

The input schema covers both parameters with descriptions, but the description adds significant value by specifying exact formats and behaviors for each type: for 'value' it gives examples (ticker, CIK, name for company; brand/generic for drug) and for 'type' it explains the return structure. This enriches the semantic meaning beyond the schema.

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

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

The description clearly states the tool's purpose: resolve a user-spoken name to a canonical/official identifier. It provides example queries and specifies supported types (company and drug), differentiating it from sibling tools like compare_entities or entity_profile by stating 'Use FIRST whenever you have a name but need an ID.'

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

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

The description explicitly says when to use this tool: 'whenever you have a name but need an ID' and 'Use FIRST.' It gives concrete examples and lists supported types with their inputs and outputs, providing clear context for usage without needing to exclude alternatives.

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

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

Annotations already indicate read-only, idempotent behavior. The description adds useful context: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. This clarifies the composite nature of the tool 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 two tight sentences plus a concise example in quotes. It front-loads the primary action and is free of redundancy. 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 specifies the return format: 'ranked list with score, confidence, signal density per entity.' It covers purpose, behavior, parameters, and usage context fully. The tool's complexity is well addressed.

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

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

Schema coverage is 100% with descriptions. The description adds extra meaning: 'First entry treated as the subject for narrative; rest are competitors.' For 'models', it clarifies default behavior ('Omit for just workers-ai') and for '_apiKey', it notes it is 'passed to api.anthropic.com per probe.' These details improve understanding beyond the schema alone.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (compare), the resource (AI visibility), and the key behavior (ranking, identifying most/least recognized). This differentiates it from siblings like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description provides a concrete use case: 'competitive AI-marketing audits: does Claude know about us as well as our competitors?' It implies that this tool is for comparing multiple entities, while single-entity checks would use ai_visibility_check. However, it does not explicitly state when not to use it or list direct alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds critical behavioral details: composite nature, partial failure handling, timing (bundlephobia first measurement 5-30s), and response structure including sources_failed. No contradictions.

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

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

Multi-sentence but every sentence adds value. Front-loaded with core purpose, then usage, ecosystem scope, failure handling. Could be slightly tighter, but 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?

For a composite tool with multiple external services and partial failure, description covers purpose, inputs, behavior, output structure (summary block, per-advisory, links, alternatives, sources_failed), ecosystem limitations, and timing. No output schema, but description sufficiently explains return values.

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

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

Schema coverage is 100%, but description adds extra context: accepts scoped packages (example '@types/node'), defaults to latest version when omitted, and mentions version format via example '18.3.1'. This enhances understanding 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?

Clear verb 'check' with specific resources ('npm package') and scope ('fans out across deps.dev and bundlephobia'). Well-differentiated from sibling tools, none of which overlap with npm scanning.

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 agent asks is X safe / popular / small' and provides concrete example ('what does adding lodash cost me'). Also clarifies ecosystem limitations ('NPM ecosystem only in v1') and fallback for other ecosystems.

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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by stating the return contents (biography, prizes, motivation), which is useful beyond the annotations.

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

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

The description is two sentences, information is front-loaded, and every sentence adds value without redundancy.

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

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

Given the tool's simplicity, the schema covers parameters, annotations cover safety, and an output schema exists (as indicated in context). The description adequately completes the picture for an agent to use the tool.

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

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

The input schema has 100% coverage and clear descriptions for both parameters. The description adds value by giving category examples ('Physics', 'Medicine'), which helps clarify the category parameter 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 searches Nobel Prize laureates by name and/or category, with a specific verb and resource. It distinguishes from siblings like 'get_prizes_by_year' which searches by year.

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 does not provide explicit guidance on when to use this tool over alternatives. Usage context is implied by the description, but no exclusions or alternatives are mentioned.

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

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

Goes beyond annotations by detailing the embedding model (BGE-base-en), windowing (500-char overlapping windows), similarity metric (cosine), character limit (200K chars with truncation flag), and return format (offsets and scores). 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?

Each sentence adds value, and the purpose is front-loaded. Slightly long but well-organized. Could be more concise but still effective.

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

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

Given no output schema, the description adequately explains return values (passages with offsets and scores), mentions the truncation behavior, and covers edge cases like cap. Could mention error handling or empty results but is largely complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema (e.g., 'max ~200K chars' for text, example for query). No additional insight for the limit parameter.

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

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

The description clearly states the tool performs semantic search inside a provided text, returns top-N passages with offsets and similarity scores. It distinguishes from sibling tools by explaining the pairing with ask_pipeworx_grounded and the use case of reducing context.

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 the record is too big to cram into the prompt') and suggests an alternative workflow ('Pairs with ask_pipeworx_grounded'). 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?

The description adds behavioral context beyond annotations: requires OAuth, delivery limitations (SMS cap, webhook signing), and that the feed is always-on. It does not explain the idempotency behavior (idempotentHint) or the openWorldHint, but the provided details are valuable.

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

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

The description is well-structured and front-loaded with the core action and return value, followed by prerequisites, supported types, and delivery options. Every sentence adds value without redundancy.

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

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

The description omits two subscription types (patent_grant and clinical_trial) that are present in the schema, and does not detail the return value structure beyond the subscription id. Since there is no output schema, more information about the response would improve completeness.

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

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

The description significantly enriches parameter semantics with concrete examples and explanations for each subscription type and delivery channel, far exceeding the concise schema descriptions. For instance, it details the meaning of items for sec_8k and the webhook signing process.

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: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This immediately distinguishes it from sibling tools like list_subscriptions 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 includes prerequisites (Pipeworx OAuth account) and details on supported types and delivery channels, aiding in appropriate usage. However, it does not explicitly contrast with sibling tools like list_subscriptions or recent_alerts, which would further guide when to use this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating safety. The description adds useful behavioral context: it uses a live catalog of tools, returns example questions, and is non-modifying. 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 relatively long but well-structured, starting with common queries, then stating purpose, then detailing output, then usage instructions. Every sentence adds value; minor redundancy with sibling tool names could be trimmed.

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

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

For an onboarding tool with no output schema, the description fully explains the return format (category-bucketed example questions with tool+argument shapes). It covers the tool's role among 27 siblings and its use case for first-time users.

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 the sole parameter 'topic' by listing specific focus values (finance, pharma, etc.) and explaining its effect (focusing the spread). This goes beyond the schema's generic description.

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

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

The description clearly states it is an onboarding entry point that returns category-bucketed example questions with tool calls. It distinguishes itself from sibling tools like ask_pipeworx and entity_profile by specifying its role as a discoverability aid.

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 agents to 'Use this FIRST' when they do not know what Pipeworx can do, and provides clear guidance on calling with no arguments for full spread or with a topic parameter to focus. This effectively differentiates when to use this tool versus alternatives.

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

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

Adds value beyond annotations by explaining ownership enforcement, deactivation (not deletion), and historical availability via recent_alerts. Annotations already indicate idempotentHint=true and destructiveHint=false.

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

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

Two sentences, no wasted words, front-loaded key action. Efficient and clear.

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

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

Given 1 parameter, no output schema, and rich annotations, the description covers purpose, ownership, behavioral outcome, and historical context comprehensively.

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

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

Schema coverage is 100%, so description adds minimal param-specific info. The phrase 'by id' reinforces the param, and schema already describes 'id' as UUID from subscribe. 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 'Cancel' and resource 'subscription by id', distinguishing it from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement ('only cancel your own subscriptions'), providing clear context. Does not explicitly list alternatives but context is sufficient.

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

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

Annotations already show read-only, idempotent, open-world. The description adds behavioral details: returns verdict, structured form, actual value with citation, percent delta, and sources (SEC EDGAR + XBRL). 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?

Front-loaded with examples and clear purpose. Slightly wordy but each sentence adds value. Could be tightened but still effective.

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

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

For a single-parameter tool with no output schema, the description covers purpose, usage, domain, and return value details. Lacks explicit output structure but sufficient for expected use.

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

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

Schema coverage is 100% for the single parameter. The description adds significant meaning with natural-language examples and supported claim types, beyond the schema 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 uses specific verbs ('validate', 'verify') and resource ('claim') with clear examples. It distinguishes itself from sibling tools by stating it replaces multiple sequential calls and is specialized for company-financial claims.

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

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

Explicitly states 'Use whenever the agent needs to check...factually correct' and defines scope (company-financial claims). Does not explicitly mention when not to use or list alternative tools, but the scope is clear enough.

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