Uuid

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds beyond this by specifying the return structure (per-model score, confidence, signals, raw_response + combined view) and that using _apiKey sends calls to Anthropic with the user bearing costs. No contradiction with annotations.

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

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

The description is a single, well-structured paragraph. It starts with the main action and output, then covers default behavior, optional parameters, and use cases. Every sentence adds 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 absence of an output schema, the description sufficiently explains the return format. All 4 parameters are well described, required parameter noted, and the tool's purpose and context are fully addressed. Sibling tools are diverse, but this description clearly distinguishes this tool's role.

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

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

Schema coverage is 100% with all parameters described. The description adds value by specifying the default model (Workers AI Llama-3.3-70b, free), clarifying that _apiKey is passed straight through to api.anthropic.com, and explaining the context parameter's purpose for disambiguation.

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 probes LLMs for knowledge of a business/brand/product/topic and scores visibility (0-100) per model. It uses specific verbs like 'probe' and 'score', identifies the resource (LLMs), and distinguishes from sibling tools like ask_pipeworx or deep_research by targeting AI visibility audits.

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 use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It explains default model and when to provide _apiKey for Anthropic, giving clear context but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: routing mechanism across thousands of tools, argument filling, citation URI output, one fast call, works on every tier. 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 front-loaded with key preference and purpose, then provides examples and step-up guidance. It is somewhat verbose (multiple sentences) but well-structured, with clear sections that are easy to scan. Every part earns its place.

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

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

Given the complexity (6 params, no output schema, many siblings), the description covers purpose, usage, behavioral traits, and parameter semantics adequately. It mentions the return type (structured answer with URIs) but could elaborate on error handling or data freshness. Overall sufficient for effective tool selection.

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 all parameter aliases documented. The description adds examples and reaffirms natural language input but doesn't significantly enhance what's already in the schema. Baseline 3 is appropriate as schema does the heavy lifting.

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 routes questions to one of 5,564 tools across 1,462 verified sources, fills arguments, and returns structured answers with citation URIs. It lists specific domains (SEC, FDA, FRED, etc.) and distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for different needs.

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 — this is the default entry point'. It provides step-up guidance: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions. Examples show when to use, and it even mentions acceptable query formulations like '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 readOnly, idempotent, and non-destructive behavior. The description adds valuable context: experimental candidate routing, current no-candidate state making it identical to stable, that it is a 'full working router' not a fallback, and that outputs are compared. 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 front-loaded with the core identity and current status. All four sentences contribute new information: beta identity, candidate mechanism, current state, usage guidance. It is slightly verbose but each sentence earns its place.

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

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

For a tool that routes to thousands of sub-tools, the description explains its purpose, experimental nature, and current equivalence to the stable version. The absence of an output schema is mitigated by stating 'same response shape' as ask_pipeworx. It does not detail failure modes but covers essential decision-making 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 description coverage is 100%, and the description does not add meaningful parameter-level details beyond referencing 'same arguments' as ask_pipeworx. Baseline 3 is appropriate since the schema already defines all six aliases for 'question'.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx with identical functionality but experimental routing improvements. It explicitly distinguishes from its stable sibling by noting candidate tests and current equivalence. The verb+resource (ask_pipeworx beta) is specific and unambiguous.

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

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

The description states 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results drive merge decisions. It implies the stable version is for production use, though it does not explicitly list when not to use this beta. The fallback clarification adds useful context.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: structured return format with {answer, evidence, confidence, source, fetched_at, refusal_reason:null} on success, explicit refusal reasons, and the cost of an extra LLM call. No contradictions.

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

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

The description is well-structured with a clear opening, process explanation, return format, and usage guidance. Every sentence is useful, though slightly verbose. Could be tightened but 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?

Given the tool's complexity (routing to 5,564 tools, no output schema), the description is thorough. It explains the return format, refusal reasons, and when to use. No output schema exists, so the description properly covers return values. Fully complete for high-stakes 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 description coverage is 100% with all 6 parameters documented as aliases for 'question'. The description does not add meaning beyond the schema; it only mentions 'natural language' which is implied. Baseline 3 is appropriate as schema does the heavy lifting.

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 'Hallucination-resistant answer mode for high-stakes reads' and explains the process of routing to the right tool and extracting answers only from tool results. It distinguishes itself from the sibling 'ask_pipeworx' by noting the grounded extraction and extra LLM call.

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 specifies when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples. Also provides an alternative: 'prefer ask_pipeworx for casual lookups' with the cost tradeoff of an extra LLM call.

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

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

Annotations already mark the tool as readOnly, openWorld, and idempotent. The description adds extensive behavioral details: low-confidence resolution handling, closed market behavior, wide spread tradeability, cancellation rule parsing, safety short-circuits, and news fallback mechanisms—all 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 very long (over 1000 words) and dense with edge cases, internal details, and examples. While valuable, it lacks conciseness and could be better structured with bullet points or sections.

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 (classifiers, fan-outs, response shapes, edge cases), the description is remarkably complete. It covers resolution confidence, parent events, news fallbacks, safety mechanisms, cancellation rules, and return shapes—all critical for correct usage, compensating for no output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: explains depth parameter (quick vs thorough), market input types, include_raw effect, and provides examples, adding significant value.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + comparison), distinguishing it from sibling tools like polymarket_edges.

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

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

Explicit usage scenarios are provided: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.' It does not explicitly state when not to use or mention alternatives, but implies context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint correctly. The description adds detailed behavioral context: for companies, it pulls specific financial metrics from SEC EDGAR/XBRL with correct fiscal year handling; for drugs, it pulls FAERS and FDA data. It also explains sorting by primary metric and citation URI generation, going well beyond annotations.

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

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

The description is concise yet comprehensive. It front-loads with common query patterns, uses bullet-like phrasing, and every sentence provides unique value. No redundancy with the schema or annotations.

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 moderate complexity (two entity types, different data sources, sorting, citations) and no output schema, the description completely covers what the tool does, what data it returns, and why it should be preferred. It leaves no critical gaps 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% with enums for type and min/max constraints for values. The description adds crucial meaning: it explains that 'company' values should be tickers/CIKs (with examples ['AAPL', 'MSFT']) and 'drug' values should be names (with examples ['ozempic', 'mounjaro']), which is not fully captured in 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 defines the tool's purpose: side-by-side comparison of 2–5 companies or drugs in one parallel call. It provides explicit examples ('X vs Y', 'rank these companies') and distinguishes from siblings like entity_profile by stating it replaces sequential single-pack lookups.

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

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

The description gives explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also lists concrete query patterns ('which is bigger', 'head to head') and specifies the number of entities (2–5), leaving no ambiguity about when to invoke this tool.

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

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

Beyond the annotations (readOnlyHint, etc.), the description adds substantial behavioral context: account requirements, paid tier for thorough depth, parallel decomposition of questions, return format with gaps[], contradictions[], hop field, citation_uri, semantic excerpts, timing expectations (15-90s), and that it never invents answers. 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 comprehensive but somewhat lengthy. It is well-structured: starts with critical prerequisites and alternatives, then defines the core action, then details parameters, return format, and edge cases. Every sentence adds value, but some repetition (e.g., mentioning gaps[] twice) could be tightened. Still, for the complexity of the tool, it earns a high score.

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 2 parameters, no output schema, but rich behavior, the description covers everything needed: prerequisites, when to use, how it works internally, the complete return packet structure (verbatim evidence, confidence, source, citation_uri, gaps, contradictions), timing, and depth-specific details. No gaps for an AI agent to invoke correctly.

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

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

The input schema already has 100% description coverage, but the tool description adds valuable semantics: it explains the depth values in detail (quick=3 facets, standard=3 with gap recovery and contradictions, thorough=6 with iterative hop) and clarifies that the question should be natural language and can be broad/multi-part since 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 the tool performs grounded multi-source research across structured data sources, decomposes questions into facets, and returns a findings packet. It uses specific verbs like 'researches' and 'returns' and distinguishes itself from sibling tools by noting it is not open-web search and is best for broad/multi-part 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?

The description explicitly tells when to use this tool versus alternatives: for single lookups use ask_pipeworx, for breaking news use ask_pipeworx, and for signed-out users use ask_pipeworx. It also specifies that the tool is best for structured data questions and explains account/payment requirements.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds valuable context: returns top-N relevant tools with full input schemas and curated examples, ready to call directly. No contradictions.

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

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

Concise yet comprehensive. Front-loaded with purpose, then usage context, then behavior. Every sentence adds value. No wasted words.

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

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

Given no output schema, description fully explains return value (tools with names, descriptions, schemas). Lists example domains and provides usage guidance. Complete for agent understanding.

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. Description enhances by providing example queries, explaining that multiple alias parameters exist, and clarifying that 'query' accepts natural language. Adds meaning beyond schema.

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

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

Description clearly states 'Find tools by describing the data or task' with specific verb and resource. It distinguishes from sibling tools by being a meta-tool for discovery, not a domain-specific tool.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. Provides clear context and when to use, implying not to use if tool is already known.

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

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

Description details the cross-source fan-out (SEC, XBRL, USPTO, news, GLEIF), specific fields returned, patents sunsetting, and soft-fail behavior. This adds significant context beyond annotations (readOnlyHint, openWorldHint, etc.).

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

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

Description is dense but not overly verbose; every sentence adds value. However, its length (8 lines) could be slightly more structured. Front-loads with examples, which is effective.

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

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

Despite no output schema, the description fully enumerates return fields (cik, company_name, recent_filings with URIs, fundamentals sorted, patents, news, LEI) and covers edge cases. 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%, but description reinforces parameter meaning: 'type' limited to 'company', 'value' accepts ticker or CIK but not names, and suggests using resolve_entity for names. Adds practical usage hints.

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 opens with example queries, clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call', and distinguishes from sibling tools by recommending it over chaining single-source lookups.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack...' and specifies when not to use: 'Names not supported (use resolve_entity first)'. This provides clear usage context and alternatives.

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

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

The description adds context beyond annotations by noting use cases for clearing sensitive data and pairing with related tools. Annotations already indicate destructive and idempotent behavior, and the description does not contradict them.

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

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

Two concise sentences that front-load the core action, with no wasted words. Every sentence serves a purpose.

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

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

For a simple one-parameter tool with no output schema, the description fully covers purpose, usage guidelines, and behavioral context, 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?

The description's 'Memory key to delete' adds no new information beyond the schema's 'Memory key to delete'. With 100% schema coverage, 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 action ('Delete') and resource ('previously stored memory by key'), distinguishing it 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 provides when-to-use scenarios ('context is stale, task is done, want to clear sensitive data') and mentions alternatives ('Pair with 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?

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds that it fetches page and extracts metadata, aligning with annotations and adding 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?

Description is well-structured: purpose first, then technical details, then use cases. Efficiently uses sentences, though slightly verbose.

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

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

Complete for a 2-param tool with no output schema. Explains output format and provides clear use cases, making it easy for an AI to decide when to invoke.

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. Description adds meaningful context: 'max_links' default 25 and max 50, and explains 'url' as full URL or landing page.

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 generates a llms.txt file for any URL, extracts title/description/key links, and emits standard markdown. Distinct from siblings; none are similar.

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 lists use cases: getting client site indexed, drafting for own project, auditing competitor crawling. 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?

Annotations provide readOnlyHint, idempotentHint, etc., establishing safety and idempotence. Description adds that UUIDs are random v4 and multiple can be generated, which is useful behavioral context beyond annotations.

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

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

Single sentence with no unnecessary words, front-loaded with the verb and resource, efficiently communicates the tool's 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?

For a simple tool with one optional parameter, rich annotations, and no output schema, the description is complete and sufficient. No missing information.

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 good description for the count parameter. The description adds no extra parameter details beyond 'one or more', 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 states verb 'Generate', resource 'random v4 UUIDs', and scope 'one or more'. Distinguishes from sibling 'validate_uuid' by specifying generation vs validation.

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 explicit when/when-not/alternatives given, but for a simple tool like UUID generation, the purpose is self-evident. Lacks explicit context about when to use this vs validate_uuid, but not misleading.

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. The description adds that the tool returns specific fields and defaults to active subscriptions, providing useful behavioral context beyond annotations.

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

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

Two concise sentences: first stating purpose and return values, second providing usage guidance. No filler, front-loaded with key information.

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

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

For a simple tool with one optional parameter and no output schema, the description covers return fields, default behavior, and usage 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 baseline is 3. The description reinforces the parameter's meaning by stating it lists 'active' subscriptions by default, adding context that aligns with 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 clearly states the verb 'List' and resource 'the caller's active subscriptions', specifying the return fields. It is distinct from sibling tools like 'subscribe' and 'unsubscribe', making the purpose unambiguous.

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

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

Explicit guidance: use before adding more subscriptions or to find an id for cancellation. This implies clear alternatives and context, aiding the agent in appropriate tool selection.

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

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

Beyond annotations (which only set all hints to false), the description discloses important behaviors: filing without an account returns a claim_token, rate limit of 5 per identifier per day, and that it is free and doesn't count against tool-call quota. It also clarifies that the team reads digests daily. This adds substantial value beyond the annotations and no contradictions exist.

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 but dense; each sentence contributes necessary information. It front-loads the core purpose and then expands into usage rules and behavioral details. While it could be trimmed, the length is justified given the complexity of the tool's workflow.

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

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

For a tool with 4 parameters, one nested object, no output schema, and no required parameters, the description covers all critical aspects: what to report, how to report, token-based follow-up, rate limits, and exclusions. It is complete enough for an agent to decide when and how to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the claim_token workflow (pass it back to read status), instructing to describe issues in terms of Pipeworx tools/packs, and emphasizing not to paste end-user prompts. This justifies a score of 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?

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly states the purpose as sending feedback to the Pipeworx team. It distinguishes this from sibling tools by explicitly contrasting with tools from other MCP servers and by focusing on feedback rather than questions or research.

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

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

Provides explicit when-to-use examples (bug, feature/data_gap, praise) and an explicit when-not-to-use (if the tool is from a different MCP server, file with that server instead). It also explains the workflow for checking previous feedback via claim_token. This fully addresses usage context and alternatives.

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

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

Annotations already declare safe behavior (readOnly, idempotent). Description adds data source (CF analytics-engine), no PII, caching window (5min-1h), and self-aggregating nature, which goes 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?

Six sentences, front-loaded with purpose, each sentence provides distinct value (returns, use cases, derivation, caching). No redundancy or fluff.

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

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

Covers all essential aspects: what it returns, when to use, data source, caching. Lacks explicit return format but acceptable given simplicity and annotations.

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

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

Single parameter 'window' has 100% schema coverage with enum. Description adds semantic guidance: shorter windows surface hot items, longer show steady-state demand, enhancing decision-making.

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 returns top tools, top packs, and total call volume over recent windows, distinguishing it from siblings like ask_pipeworx and discover_tools. Specific verb+resource plus enumerated use cases.

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

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

Lists three explicit use cases showing when the tool is valuable. Does not mention when to avoid it or contrast with alternatives, but context is clear enough for selection.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description details internal mechanics: date-axis/threshold-axis ordering, partition check with 3pp threshold, Jaccard similarity filter, placeholder detection, fill check logic. This fully reveals how the tool behaves.

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 but well-organized: it starts with the core purpose, then breaks down modes, and includes detailed sub-sections (semantic anchor, partition filter, fill check). Every sentence contributes actionable information, though some trimming could improve conciseness.

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

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

Despite lacking an output schema, the description fully documents the return structure (opportunities[] fields, partition_check fields, fill check details). It covers all relevant aspects—modes, filters, edge cases—making it self-contained and complete.

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

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

The schema already describes both parameters with high coverage, but the description adds significant value with mode explanations, example slugs and seed questions, and behavioral semantics (e.g., how cross-event works). This goes beyond mere schema documentation.

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

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

The description clearly states the tool's function: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) with specific examples for each, making the purpose very clear.

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

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

The description explicitly explains when to use each mode (trending scan vs. event vs. topic), provides guidance on parameter selection, includes conditions for not trading (fill check), and references a sibling tool for custom sizing. This provides excellent decision support.

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 (readOnlyHint, idempotentHint, etc.) by detailing caching (1h KV level), model families, edge calculation net of slippage, response structure by segment, and tradeable-edge knobs. No contradiction with annotations; it adds rich 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 long but densely packed with valuable, well-organized information. It front-loads the purpose, then details the three model families in numbered segments, and ends with caching and diagnostics. Every sentence earns its place; no fluff.

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

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

Given the tool's complexity (9 parameters, no output schema), the description provides comprehensive context: it explains the response structure (by_segment, fed_candidates, _diagnostics), caching, and the role of each knob. An agent can fully understand what the tool returns and how to use it effectively.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning beyond the schema, such as explaining that min_partition_leg_kelly applies when min_kelly doesn't filter partitions, and that slippage_pp accounts for bid/ask spreads. This added context justifies a score higher than 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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the verb (scan, return) and resource (opportunities), and distinguishes from siblings like polymarket_arbitrage by detailing its edge-finding model families. The phrase 'built for what should I bet on today' provides an explicit use case.

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 extensive guidance on when to use (e.g., 'agents discover opportunities'), explains knobs like min_liquidity and max_spread_pp, and includes diagnostics to understand empty segments. However, it does not explicitly mention when not to use or suggest alternative tools like polymarket_arbitrage for pure arbitrage, which would improve this dimension.

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 substantial behavioral context beyond the annotations, including details about history depth (bounded by 60-day TTL), snapshot timing, decay computation (daily closes, not intraday), and a full breakdown of the response structure (tracked, expired, snapshot_dates). 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 front-loaded with purpose and key details, then systematically covers response structure and limitations. While somewhat lengthy, each sentence adds value and the structure is logical. Could be slightly more concise but remains functional.

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, rich annotations, and lack of output schema, the description fully compensates by explaining the response fields (tracked, expired, snapshot_dates) and limitations (TTL, snapshot start). It provides all necessary context for correct 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%, so baseline is 3. The description restates parameter info (days lookback, window family) without adding new semantic meaning beyond what is in the schema. It does not elaborate on how parameters interact or affect output.

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's purpose: providing edge persistence and decay telemetry from daily polymarket_edges snapshots. It explicitly answers a specific question about edge duration and trend, distinguishing it from related tools like polymarket_edges.

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

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

The description gives context for when to use the tool (e.g., differentiating fresh vs. old edges), but does not explicitly state when not to use it or mention alternative tools. It provides clear use-case guidance without 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are fully consistent with the description. The description adds rich behavioral context: walks the order book ladder, returns multiple fill metrics, highlights thin legs and forced directional risk, and warns about partial fills. Contradiction is 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?

The description is long but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET) and front-loaded with the core purpose. Every sentence adds value; no redundancy. Minor deduction for verbosity 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 the complexity (two modes, no output schema), the description is highly complete. It explains return fields, mode-specific behavior, risks (thin_legs, forced_directional_risk), and usage context. No gaps left for an agent.

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

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

Schema description coverage is 100%, but the description adds substantial meaning beyond the schema: explains mode-dependent defaults for side, interprets size_usd differently for single-market vs basket, details output fields for each mode. This far exceeds the baseline of 3.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes from siblings by specifying 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Two modes are explicitly separated.

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

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

Explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why alternatives fail: 'theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position'.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description goes well beyond by detailing safety fields (compatibility_warning, temporal_alignment, skipped counters) and explaining conditions for meaningful spreads. 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 lengthy but every sentence adds critical information. It is front-loaded with the core purpose. Minor structure improvements could be made (e.g., using bullet points for modes/fields), but it remains efficient given the tool's complexity.

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

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

Despite lacking an output schema, the description thoroughly outlines the response structure: leg-by-leg prices, matched spread, top_spreads_pp, safety fields, and alignment indicators. This provides complete context for an agent to understand and use the tool correctly.

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

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

Schema has 3 parameters with 100% coverage (descriptions and examples). The description adds significant value by explaining the two modes, the topic shortcut list, and how explicit tickers override mapped values. This enriches understanding beyond 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 computes 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It uses specific verbs ('compute', 'fetches') and distinguishes from siblings by focusing on cross-venue comparison, while siblings like polymarket_arbitrage are venue-specific.

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

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

Describes two explicit modes ('topic' shortcuts and custom pairings) and provides clear context on when to use each. Includes important caveats like 'pre-mapped ≠ tradeable' and that most shortcuts return compatibility warnings. However, it doesn't explicitly contrast with alternative tools that might also compare venues (e.g., 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows it's a safe read operation. The description adds useful context: scoping to identifier (anonymous IP, BYO key hash, account ID) and pairing with remember/forget, which goes beyond the annotations.

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

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

The description is three sentences, starting with the primary purpose. Each sentence contributes: action, use cases, and scoping/pairing. It is front-loaded and efficient, though slightly longer than minimal.

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

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

Given one optional parameter, no output schema, and rich annotations, the description covers all necessary aspects: retrieval vs listing, scoping, and relationship to sibling tools. No gaps are apparent for this simple memory 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?

Schema coverage is 100% with one parameter described. The description adds value by explaining the behavioral effect of omitting the key (list all keys), which is not in the schema description. This clarifies the dual mode of the tool.

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 retrieves a value saved via remember or lists all keys when key is omitted. It specifies the action (retrieve/list), resource (saved memory), and distinguishes from siblings like remember and forget with concrete examples (ticker, address, notes).

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

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

The description explicitly tells when to use the tool: to look up previously stored context without re-deriving it. It also explains the omitting-key behavior for listing. While it does not explicitly state when not to use, the pairing with remember and forget provides 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 indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond annotations, such as returning specific fields (source, citation_uri, raw payload), the mark_read flag affecting subsequent calls, and the existence of an alternative endpoint. 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 front-loaded with the purpose and provides multiple sentences, each adding value. It is not overly verbose but could be slightly more concise without losing 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 there is no output schema, the description clearly states what the return values include (source, citation_uri, raw event payload). It covers filtering, pagination (limit), state management (mark_read, unread_only), and mentions polling and an alternative endpoint. It is complete for a read-only feed tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining what the 'type' filter expects (e.g., 'sec_8k'), that 'since' should be an ISO timestamp, and the effect of 'mark_read' and 'unread_only'. This 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?

The description starts with 'Pull fired events from your subscription feed,' specifying the verb 'Pull' and the resource 'fired events' with clear context (from subscription feed). It distinguishes itself from sibling tools by mentioning specifics like source, citation_uri, and raw event payload, and it is not a tautology.

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

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

The description provides clear guidance on when to use the tool, including filtering by type and since, setting mark_read, and polling. It also mentions an alternative endpoint for scripts/dashboards. However, it does not explicitly state when not to use it or contrast with siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds detailed behavior: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail, and returns structured changes with citation URIs. 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 thorough and front-loaded with examples, but slightly longer than necessary. However, each sentence adds value, so it is 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 (multiple sources, fallback behavior, soft-fail), the description covers all essential aspects. Although there is no output schema, the description states the return structure (changes[] grouped by source + total_changes count + pipeworx:// citation URIs), 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 all three parameters. The description adds extra value: explains accepted formats for 'since' (ISO date or relative shorthand with examples), recommends '30d' or '1m', and clarifies 'value' accepts ticker or CIK.

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 change feed for a company in the last N days/weeks/months, fetching filings, news, and patents. It distinguishes from the sibling tool entity_profile, which is for static profiles.

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

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

Explicitly provides when to use this tool and when to use entity_profile instead. Also includes example queries like 'What's new with X' and 'latest on Y'.

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

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

Annotations indicate idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds behavioral context: memory is scoped by identifier, persistent for authenticated users, and 24-hour retention for anonymous sessions. No contradiction with annotations.

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

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

The description is concise and well-structured. It opens with the primary purpose, then provides usage examples, and ends with pairing instructions. 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 is complete for the tool's simplicity. It explains the storage semantics, scope, and lifetime. Despite no output schema, the behavior is fully disclosed.

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 parameter descriptions. The description adds context by providing naming conventions (e.g., 'subject_property', 'target_ticker') and explaining the key-value nature, but could be slightly more detailed about formatting expectations.

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 purpose: 'Save data the agent will need to reuse later.' It specifies the verb (save/store) and resource (key-value pair), and distinguishes from sibling tools like recall and forget by mentioning 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?

The description provides explicit guidance on when to use: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject).' It also mentions alternatives for retrieval (recall) and deletion (forget).

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 the annotations (readOnlyHint, idempotentHint, etc.) by disclosing graceful degradation ('LEI/FIGI enrichment degrades gracefully...'), the explicit handling of unresolvable identifiers ('stated explicitly under `unresolved` rather than omitted'), and the internal cascading of multiple lookups. These details are valuable context not available in annotations.

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

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

The description is long and dense, but it is well-structured: it starts with user-phrased examples, then gives a crisp purpose statement, followed by a SUPPORTED TYPES breakdown. Every sentence contributes substantive details like fallback behavior and cross-source coverage, though the length could be intimidating. It earns a 4 rather than 5 due to slightly excessive verbosity.

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 the absence of an output schema, the description is remarkably complete. It explains return values for both entity types, handles edge cases (ISIN-to-LEI mapping for non-US issuers), discloses fallback behavior, and even mentions citations for drugs. It covers everything an agent needs to decide if this tool is appropriate and what to expect.

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

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

The schema already covers both parameters at 100%, but the description adds substantial meaning: it explains accepted input formats for `value` (e.g., 'ticker (AAPL), CIK (0000320193), or name' for companies) and details what each `type` returns (CIK, LEI, FIGI for company; RxCUI, ingredient, brand for drug). This goes well 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 clearly states the tool's purpose with concrete query examples ('What's the ticker for…', 'find the CIK for…') and explicitly says it 'resolve[s] a user-spoken NAME to the canonical/official identifiers other tools require as input.' This distinguishes it from siblings like entity_profile and compare_entities, which likely consume those identifiers. The phrase 'Use FIRST whenever you have a name but need an ID' further solidifies its unique role.

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

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

The description provides explicit guidance on when to use it: 'Use FIRST whenever you have a name but need an ID.' It also lists accepted input formats for each type (company: ticker, CIK, ISIN, name; drug: brand or generic name), which helps the agent decide. However, it does not name alternative tools or explicitly state when not to use it, so it stops short of a full 5.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds details beyond annotations, such as 'Probes each entity with ai_visibility_check', 'ranks by score', and returns 'ranked list with score, confidence, signal density per entity'. There is no contradiction.

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

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

The description is three sentences front-loaded with the core purpose. Every sentence provides value: purpose, method, output. No redundant or filler words. Excellent structure.

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

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

Despite no output schema, the description fully describes the output format (ranked list with score, confidence, signal density). All parameters are covered in schema and description. The tool's complexity is well-addressed, leaving no significant gaps 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 description coverage is 100% with clear descriptions for all 4 parameters. The description adds extra context, e.g., 'First entry treated as the 'subject' for narrative; rest are competitors,' and implies default behavior for models. This enriches 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 tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (Compare), resource (AI visibility), and distinguishes from sibling 'ai_visibility_check' which checks single entities. It provides a concrete example use case ('does Claude know about us as well as our competitors?'), leaving no ambiguity.

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

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

The description provides context on when to use ('competitive AI-marketing audits') and hints at alternatives by mentioning 'ai_visibility_check'. However, it does not explicitly state when not to use this tool versus siblings like 'compare_entities' or 'ai_visibility_check'. A more explicit directive would improve 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?

Descriptiom adds critical behavioral context beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description explains failure modes and timing.

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 front-loaded purpose, but is slightly verbose. Every sentence adds value (e.g., ecosystem limitation, failure details), though some could be tightened. Still above average for conciseness.

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 (composite check with multiple external sources), the description is highly complete. It covers return summary fields, failure behavior, timing, and ecosystem scope. Annotations already provide safety and idempotency context. No output schema exists, but the description lists all returned fields 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 covers both parameters with descriptions (100% coverage). The description adds extra value: scoped packages are accepted, and version defaults to latest. This is a minor addition over the schema, justifying a score of 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?

The description clearly states it's a composite check for npm packages covering license, advisories, version history, and bundle size. It uses specific verbs like 'scan', 'fans out' and distinguishes itself from sibling tools by being a single-call composite for npm dependency evaluation.

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 agent asks about package safety, popularity, size, or cost. Also clarifies ecosystem scope (NPM only in v1) and directs other ecosystems to deps.dev:version directly. This provides clear when-not-to-use guidance.

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

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

Annotations already declare safety traits (readOnly, idempotent, etc.). The description adds critical behavioral details: 200K char cap with truncation flag, embedding model, window size, and similarity metric. 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 paragraphs: first covers purpose and usage, second technical details. Every sentence adds value, no fluff. Front-loaded with key info.

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 mentions return values (passages with offsets and scores). Covers constraints, behavior, and integration with sibling tool. Complete for this complexity.

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

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

Schema coverage is 100% and description adds meaning: explains what 'text' means (e.g., SEC 10-K), gives query examples, and clarifies the limit default. Goes beyond schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes itself from sibling tools like ask_pipeworx_grounded by focusing on passage retrieval rather than grounded 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 says when to use (record too large for prompt) and pairs with a sibling tool (ask_pipeworx_grounded). No explicit when-not, but the use case is well-defined.

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 implies non-idempotent behavior ('Create a... subscription... Returns the new subscription id') while annotations declare idempotentHint=true. This is a clear contradiction, mandating a score of 1 per guidelines.

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 well-structured with clear sections for types and delivery channels, uses bullet-like formatting with colons and examples. Every sentence adds useful information without redundancy.

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

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

Despite no output schema, the description covers prerequisites, all parameter options, return value ('Returns the new subscription id'), and behavioral nuances (cap, auto-disable). This is complete for a creation 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%, and the description adds significant value by providing concrete examples for each subscription type and delivery channel, including constraints (phone verification, 10/day cap, webhook auto-disable).

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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb+resource pair that distinguishes 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?

Description provides prerequisites (requires Pipeworx OAuth account), lists supported types with examples, and details delivery channel constraints. However, it does not explicitly state when to use this vs alternatives like ask_pipeworx or deep_research, leaving a minor gap.

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, and non-destructive behavior. The description adds valuable context about the return format (category-bucketed example questions with tool shapes) and the effect of the topic parameter, going beyond the structured 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 somewhat lengthy but front-loaded with the tool's purpose starting from common user questions. Every sentence provides unique value, though minor trimming could improve conciseness 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 no output schema, the description fully explains the return format (category-bucketed example questions with exact tool and argument shapes). It covers parameter usage, use cases, and relationship to sibling tools, making it complete for a single-parameter tool.

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

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

Schema coverage is 100%. The description adds meaning by explaining that omitting the topic gives a cross-category spread, and provides example values ('finance', 'pharma', 'betting') that are not in the schema, clarifying how to use the optional 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 is for onboarding, providing category-bucketed example questions. It uses specific verbs like 'return' and 'call', and distinguishes itself from siblings by explicitly recommending it as the first call when unfamiliar with Pipeworx.

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

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

The description explicitly advises when to use this tool ('when you do not yet know what Pipeworx can do for you') and offers a concrete alternative by referencing meta-tools. However, it does not explicitly state when not to use it.

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

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

Discloses ownership enforcement, deactivation behavior, and persistence of historical events. Adds significant context beyond annotations (destructiveHint=false, idempotentHint=true). 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, first states action and constraint, second explains effect. No wasted words.

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

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

For a simple cancellation tool with one required parameter, the description covers purpose, constraints, effect, and data persistence. 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 coverage is 100% with clear description of 'id' parameter. Description adds no extra parameter info; 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 verb 'Cancel' and resource 'subscription by id'. 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?

Explicitly says ownership is enforced, indicating when to use. Explains the effect (deactivation vs deletion). No explicit alternative named, 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 readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral context: the dual-path routing, the meaning of could_not_verify (failure with verification_error, not evidence) and unsupported (no source coverage), and the return of a verdict with citation. This goes well beyond the annotations.

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

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

The description is long but well-organized: trigger examples, usage statement, path details, return format, and a caller caution. Each sentence contributes necessary information for a complex verification tool, with no filler; however, it is more verbose than needed for a simpler 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?

With no output schema, the description fully compensates by enumerating the possible verdicts (confirmed, approximately_correct, etc.), explaining the actual value and citation, and detailing failure semantics. It also covers the two execution paths, giving an agent a complete picture of expected outcomes.

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 provides full descriptions for both parameters (claim and tolerance_pct) at 100% coverage. The description mentions 'exact percent-delta math' and tolerance behavior but does not materially enhance parameter understanding beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool performs 'natural-language claim verification against authoritative sources' with concrete trigger phrases and examples. It differentiates from siblings by focusing on fact-checking and explicitly notes it replaces 4–6 sequential calls, leaving no ambiguity about its purpose.

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 provides an explicit 'Use whenever the agent needs to check whether something a user said is factually correct' and describes the two processing paths (company-financial vs. other factual claims). However, it does not explicitly name a sibling alternative or state when not to use the tool, but the replacement note and fallback behavior give strong guidance.

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

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

Annotations already declare readOnlyHint, etc., and the description adds that it is keyless, offline, and returns specific fields like version and timestamp only for v1/v7. 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 one sentence, well-structured, front-loaded, and contains no unnecessary words. Every detail earns its place.

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

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

Despite no output schema, the description thoroughly explains return values (version, variant, nil/max, timestamp for v1/v7) and usage context (keyless, offline), fully covering the tool's behavior.

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

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

With 100% schema coverage for a single string parameter, the description does not add new parameter-level detail beyond what the schema provides, resulting in a baseline score.

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

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

The description specifies a clear verb ('Validate and parse') and resource ('UUID'), and distinguishes from sibling tools like 'generate_uuid' and 'validate_claim' by detailing the specific parsing behavior.

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 hints at usage context with 'keyless, offline,' but does not explicitly state when not to use or compare to alternatives. However, the uniqueness of UUID validation relative to siblings makes it clear.

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