Walkscore

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds value by detailing the return structure (per-model fields and combined view) and cost implications for Anthropic. No contradictions.

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

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

The description is a single paragraph with front-loaded main action. Every sentence adds value, no redundancy. Efficient and clear.

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

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

For a tool with 4 parameters and no output schema, the description covers purpose, usage, and return structure well. It lacks explicit output format specification but is otherwise comprehensive. Could mention error handling.

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 meaningful context: default model is free, _apiKey enables Anthropic costing, and context helps disambiguate. This goes beyond the schema descriptions.

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

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

The description clearly states it probes LLMs about an entity and returns a visibility score. It uses specific verbs and resources, and distinguishes from siblings like scan_competitor_ai_presence by focusing on general brand/topic visibility.

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

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

The description explains when to use (AI-marketing audits, pre-launch checks) and how to use (default model, optional Anthropic key). It does not explicitly state when not to use, but the context is clear. Could be improved by contrasting with sibling tools.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds rich behavioral context: it routes to one of 5,529 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and works on every tier with one fast call. 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 well-structured and front-loaded with the key preference directive. It covers when, what, and how in a logical flow, but it is somewhat long. Every sentence contributes value, though trimming could improve conciseness without losing meaning.

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

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

Given the tool's complexity (routing across 5,529 tools) and the presence of rich annotations and full schema coverage, the description provides sufficient context. It explains the return format (structured answer with citation URIs) and positions the tool within the broader toolset, making it complete for an agent.

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

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

Schema coverage is 100% with all parameters documented as aliases for 'question'. The description adds examples of natural language queries but does not provide additional parameter-level semantics beyond what the schema already includes. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: it routes questions to a vast set of sources and returns structured answers with citations. It explicitly differentiates itself from siblings like ask_pipeworx_grounded and deep_research, and even from web search, making it the default entry point for factual queries.

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

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

Provides explicit guidance on when to use: triggers like 'what is', 'look up', 'find', 'get the latest', and states to prefer over web search. Also gives clear exclusions: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions, plus notes on breaking-news handling.

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, the description discloses that routing improvements are enabled live during tests, that no candidate is currently active, and that the tool is a full working router rather than a fallback. This significantly enriches the behavioral context without contradicting the readOnly, openWorld, idempotent, and non-destructive hints.

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

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

The description is front-loaded with the core identity and relationship to ask_pipeworx. It is somewhat verbose with the parenthetical and the emphatic last clause, but each sentence adds meaningful context about experimental status, usage, and equivalence.

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

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

The description covers purpose, usage, current experimental state, and relationship to the stable router. Although there is no output schema, it points to the same response shape as ask_pipeworx, which is sufficient for this tool's simple interface and sibling 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?

The input schema covers 100% of parameters with clear descriptions for each alias, so the description need not repeat them. It only says 'same arguments as ask_pipeworx,' which adds no new semantic detail 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 identifies this as the beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It explicitly distinguishes itself from the stable ask_pipeworx by its experimental routing improvements and current equivalence.

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 clear usage context: use it exactly like ask_pipeworx when wanting the newest routing, and it notes that results are compared to the stable router. It does not explicitly state when not to use it, but the contrast with ask_pipeworx and the beta/experimental framing imply the exclusion.

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 (readOnly, openWorld, idempotent, non-destructive), the description discloses key behavioral traits: it uses ONLY the tool result to extract answers, returns specific refusal reasons, and costs an extra LLM call. This provides substantial context not available from annotations or schema.

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

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

The description is dense but well-structured, front-loading the core purpose ('Hallucination-resistant answer mode') and then systematically covering process, output format, usage context, and cost. Every sentence adds non-redundant value, making it appropriately sized for a complex tool.

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

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

With no output schema, the description fully compensates by specifying the exact return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and all possible refusal reasons. It also addresses when to use, cost implications, and alternatives, making it complete for high-stakes decision-making.

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

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

The input schema already provides 100% coverage of all 6 parameters, describing each as an alias for the 'question' field. The description adds no parameter-specific meaning beyond what the schema states, 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 identifies the tool as a hallucination-resistant answer mode for high-stakes reads, with a specific verb ('extracts') and resource ('tool result'). It explicitly distinguishes itself from the sibling tool ask_pipeworx by noting the grounded extraction step, making its unique purpose 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 provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also defines when NOT to use it ('prefer ask_pipeworx for casual lookups') and states a trade-off (extra LLM call), naming the alternative.

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

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

Annotations indicate readOnlyHint=true and destructiveHint=false, which are consistent. The description adds rich behavioral details: resolution process, fan-out logic, response shapes, resolver contract, parent event extraction, news fallback, safety mechanisms (low-confidence short-circuits, closed markets), tradeability warnings, and cancellation rule parsing. No contradictions.

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

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

The description is long but well-structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It is front-loaded with the main purpose and examples. Every sentence provides essential information for a complex tool, so the length is justified. Not concise but not 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?

Given the complexity (multiple input types, fan-outs, response shapes, safety checks) and lack of output schema, the description is remarkably complete. It covers return values, edge cases (low confidence, closed markets, wide spreads), cancellation rules, and fallback mechanisms. No gaps are evident.

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

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

Input schema covers 3 parameters with 100% description coverage. The description adds context: depth defaults to 'thorough', include_raw defaults to false, market accepts slug/URL/question text. It explains the meaning of quick vs. thorough and raw vs. summarized, adding significant value beyond the schema.

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

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

The description clearly states the tool's purpose: research a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on research, not arbitrage or edge tracking.

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

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

The description explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It provides extensive examples of classifiers and fan-outs, giving clear context. However, it does not explicitly state when not to use or list alternatives, so it falls short of a 5.

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

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

Annotations already indicate safe, idempotent, read-only behavior. The description adds valuable context about data sources (SEC EDGAR for companies, FAERS for drugs), fiscal year handling, and result sorting, without contradicting annotations.

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

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

Concise 5-6 sentences, front-loaded with trigger phrases, then details. Every sentence adds value (data sources, sorting, performance note). No waste.

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

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

For a comparison tool with no output schema, the description explains inputs, data sources, sorting, and citation URIs. Could be more explicit about output format, but sufficient for typical use.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameter meaning (e.g., what 'company' pulls) but does not provide critical missing info beyond the schema.

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

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

The description clearly states the tool does side-by-side comparison of 2-5 companies or drugs. It distinguishes from sibling tools like entity_profile by emphasizing it replaces multiple sequential lookups and lists trigger phrases like 'Compare X and Y'.

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 triggers and preference over sequential lookups. However, it does not explicitly state when not to use (e.g., above 5 entities) but the schema's maxItems=5 enforces that.

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 readOnly/openWorld/idempotent annotations, the description discloses extensive behavioral traits: account requirements, paid tier for 'thorough', decomposition into facets, parallel routing to 5,529 tools, return packet contents (evidence, confidence, source, cited URIs), explicit gaps[] for unanswered facets, contradictions[] for standard/thorough, semantic excerpting, and latency expectations. 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 long but densely packed with unique value. It front-loads the critical account requirement and main differentiator, then logically flows through usage, limitations, output format, and performance. A few redundancies (e.g., repeated mention of ask_pipeworx) could be trimmed, but overall it earns its length for a complex tool.

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

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

With no output schema, the description fully explains return values: findings with verbatim evidence, confidence, source, fetched_at, citation URIs, gaps[], contradictions[], and hop fields. It also covers timeout behavior, second-hop iteration, and semantic excerpting. Given the tool's complexity (5,529 tools, multiple depth levels), this is essentially 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%, but the description massively enriches parameter meaning. For 'depth', it explains hop behavior and contradiction scanning beyond the enum labels. For 'question', it confirms broad/multi-part questions are acceptable and highlights decomposition as the tool's purpose. This adds operational context far beyond the schema.

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

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

The description clearly states the tool performs grounded multi-source research across 1,455 structured data sources in a single call, explicitly distinguishing it from open-web search and sibling tools like ask_pipeworx. It uses a specific verb ('research'), names the resource (Pipeworx structured data), and clarifies scope (multi-source, one 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?

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx'. It also names exclusions (breaking/current-news topics should use ask_pipeworx) and provides a fallback for non-signed-in users. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds important detail: it returns full input schemas with curated examples, ready to call. No contradictions. Adds value beyond annotations.

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

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

The description is a single paragraph but conveys all key information efficiently. It is front-loaded with purpose. Could be slightly improved with bullet points, but overall concise.

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

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

Given no output schema, the description explains what is returned (names, descriptions, full schemas, examples). It covers purpose, usage, and result format. Missing details like pagination or error handling, but adequate for this tool.

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

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

Schema coverage is 100%, so baseline is 3. Description mentions that query accepts aliases and gives examples, but does not add significant detail beyond the schema's own parameter descriptions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and explains it returns top-N relevant tools with schemas. This distinguishes it from siblings like search_within or deep_research.

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

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

Explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use and prioritization.

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

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

Beyond annotations (readOnlyHint, etc.), the description discloses that the patents API may soft-fail after May 2025, and details the returned fields (cik, filings, fundamentals, etc.). 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 fairly long but front-loaded with example queries and a clear summary. Every sentence adds value, though slight abbreviation 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?

Given the tool's complexity and lack of output schema, the description thoroughly covers what the tool returns (fields, sources, URIs, fallbacks) and known limitations (patents API sunset). It is fully informative.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that 'value' accepts ticker or zero-padded CIK and that 'type' is limited to 'company'. It also clarifies that names are not supported.

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

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

The description explicitly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call' and provides example queries. It distinguishes itself from sibling tools by advising preference over chaining single-pack lookups.

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

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

The description gives clear when-to-use guidance ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and when-not-to-use ('names not supported — use resolve_entity first'). It also warns about the patents API sunset.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about clearing data and sensitive data but does not detail side effects (e.g., permanence, error behavior). Since annotations cover the core behavioral traits, the description adds moderate value.

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: purpose, usage guidelines, and sibling reference. Every sentence is valuable, no wasted words, and the most critical information is front-loaded.

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

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

Given a single parameter, existing annotations, and no output schema, the description covers purpose, usage, and tool relationships. It does not mention error behavior for missing keys, but overall it is sufficient for a simple destructive 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 the parameter 'key' described as 'Memory key to delete'. The tool description does not add further parameter semantics beyond the schema. With high schema coverage, baseline is 3.

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

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

The description explicitly states 'Delete a previously stored memory by key', clearly identifying the verb (delete) and resource (memory by key). It distinguishes from sibling tools like 'remember' and 'recall' by specifying the deletion action and referencing their pairing.

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

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

The description provides explicit usage scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also suggests pairing with siblings. However, it does not explicitly state when NOT to use or provide 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown format. This explains the process without contradicting annotations. No side effects are mentioned beyond fetching.

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 long, front-loading the core purpose and audience, then briefly explaining the process, and finally listing use cases. Every sentence adds value, with 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?

The description explains the output format ('single text blob ready to drop at site-root/llms.txt') and the process (fetch, extract, emit). It lacks details on error handling or edge cases (e.g., invalid URL), but for a simple generation tool with good annotations, it is largely complete.

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

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

Schema description coverage is 100%, so baseline is 3. The tool description does not add any parameter-level meaning beyond what the schema already provides (e.g., url as full URL, max_links with defaults). No new semantics are introduced.

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

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

The description uses a specific verb ('Generate') and resource ('llms.txt file') and clearly states the tool's purpose: to create a production-ready llms.txt for any URL so AI crawlers can index the site. It also lists concrete use cases (e.g., getting a client's site indexed, drafting for own project, auditing competitors), which distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

The description explicitly states when to use the tool via the 'Useful for' list, covering scenarios like indexing a client's site, drafting for a project, or auditing competitors. It does not explicitly state when not to use it, but the context is clear enough for an AI agent to infer appropriate usage.

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

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

Annotations already declare safe, idempotent, and read-only. The description adds nuance: defaults to active subscriptions only, and lists specific return fields, providing transparency beyond annotations.

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

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

Two sentences: first sentence concisely communicates purpose and return fields; second sentence provides usage guidance. No wasted words.

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

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

Given no output schema, the description lists all return fields. It explains default behavior and provides usage scenarios. Complete for a simple list tool with one optional parameter.

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 parameter description is already provided in the schema. The description implies the default (active) but does not add new information beyond the schema.

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

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

Clearly states the action (list) and the resource (the caller's active subscriptions). Specifies the returned fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Provides explicit usage context: use to review before adding more subscriptions or to find an id to cancel. This helps an agent know when to invoke it versus alternatives.

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

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

Annotations are all false (readOnly, openWorld, idempotent, destructive) and offer no insight. The description compensates fully by revealing rate limits (5/day/identifier), free usage (no quota), the claim_token follow-up mechanism, and how the team processes feedback. It even explains behavior when no account is provided. 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 dense but every sentence serves a purpose: purpose, when-to-use, when-not-to-use, message guidance, token mechanics, rate limits, and cost. It is front-loaded with the main verb and resource, then expands logically. No filler or 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 explains what to expect (a claim_token when filing without an account, and status updates later). It covers all necessary operational details: rate limiting, cost, and follow-up workflow. For a feedback tool of this complexity, nothing important is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra semantics beyond the schema: how to use claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), message formatting guidance ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), and typical message length. This is meaningful added value, earning a 4.

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

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

The description states a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes from sibling tools like ask_pipeworx or discover_tools by focusing on feedback, not Q&A or discovery.

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

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

Usage is explicitly codified: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives an explicit exclusion for tools from other MCP servers and tells users to file elsewhere. This is a textbook when-to-use/alternatives explanation.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: data is self-aggregating, derived from CF analytics-engine, no PII, and cached with varying durations. This provides transparency 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 appropriately sized for a simple tool, front-loading the main purpose, then listing use cases and technical details. It could be slightly more concise but remains clear and readable.

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

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

No output schema, but description adequately explains return values (top tools, top packs, total call volume). Given tool simplicity and a single optional parameter, the description provides sufficient context for invocation.

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

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

Schema coverage is 100% with enum descriptions. Description adds semantic nuance: shorter windows surface 'hot right now', longer show 'steady-state demand', justifying the parameter's role.

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 returns trending tools, packs, and call volume from Pipeworx, with explicit use cases. It distinguishes itself from siblings by focusing on trending data derived from other agents' activity, not on individual queries or entity 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?

Three explicit use cases are given (discovering hot data sources, confirming canonical tools, aligning use cases). The description implies when to use it but does not explicitly state when not to use it or mention alternatives among 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?

The description adds extensive behavioral context beyond annotations: explains algorithm details (monotonicity checks, partition sum), semantic anchor (Jaccard ≥0.30), partition filter (placeholder slugs), fill check (realizable vs theoretical edge), and cross-reference to polymarket_fill_risk. No contradictions with annotations (readOnlyHint=true aligns with scanning).

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 clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and contains no wasted sentences. However, it is somewhat verbose (≈300 words) for a tool with only two optional parameters; a slightly more condensed version could improve conciseness without losing value.

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

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

Given the tool's complexity (multiple modes, algorithms, filters) and absence of an output schema, the description covers most needed context: input modes, detection logic, filters, fill check, and cross-reference. It briefly describes output fields (opportunities[], partition_check) but could provide more explicit detail on exact return structure for full completeness.

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

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

Schema coverage is 100% (both parameters described), but the description adds significant value: explains behavior with no args (trending_scan), details what 'event' mode does (walks child markets, date-axis/threshold-axis checks, partition_check), and what 'topic' does (cross-event scanning with similarity filter). Also clarifies acceptable input formats (slug or URL).

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

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

The description clearly states the tool's action ('Find arbitrage opportunities'), resource ('on Polymarket'), and method ('via monotonicity violations + partition-sum checks'). It distinguishes from sibling tools by specifying the unique detection algorithms and explicitly referencing related tools (e.g., polymarket_fill_risk).

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

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

The description provides explicit guidance on when to use each parameter: no args for trending scan, 'event' for specific market (recommended), 'topic' for cross-event scanning. It explains trade-offs (cross-event catches patterns single-event misses) and gives recommendations, making it clear when to use each mode.

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, and destructiveHint=false. The description adds rich behavioral context: model families, edge calculation, tradeable-edge knobs, diagnostics, caching, and excluded Fed bets. 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 verbose and includes highly technical details (e.g., 'lognormal barrier from 90d FRED log-returns') that may not be necessary. It is structured well and front-loaded, but could be more concise.

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

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

With no output schema, the description fully explains the response structure, including segments, diagnostics, and per-opportunity fields. It covers caching, knobs, and segment-specific behaviors, making the tool understandable for an agent.

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

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

Schema coverage is 100% with descriptions for all 9 parameters. The tool description adds extra context by grouping parameters into 'tradeable-edge knobs' and explaining their interaction, which goes 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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It is built for 'what should I bet on today', distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description explains when to use the tool ('agents discover opportunities without paging hundreds of markets') and provides extensive details on knobs and filtering. It implicitly contrasts with siblings, though it lacks explicit 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 indicate readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond annotations: history depth bounded by 60-day TTL, snapshots written on cache-miss, decay from daily closes not intraday. These details help the agent understand limitations.

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

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

The description is well-structured: it starts with the core question, then details the response format, and ends with limits. Although lengthy, every sentence adds value. Some redundancy could be trimmed.

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

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

Despite lacking an output schema, the description thoroughly documents the response structure (tracked[], expired[], snapshot_dates[]) including all fields and their meanings. Parameter coverage is complete, and behavioral constraints are explained. This provides sufficient context for the agent.

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

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

Schema coverage is 100% with both parameters described. The description reinforces defaults and limits but adds little new information beyond the schema descriptions. Thus, it meets the baseline of 3.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots. It answers a specific question about edge duration and decay, distinguishing it from the sibling tool 'polymarket_edges' which likely focuses on current edges.

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

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

The description explicitly states the use case: answering how long an edge has existed and whether it is shrinking. It implies when not to use (e.g., for current edges without history) but does not explicitly list alternatives. However, the limits section provides important constraints like 60-day TTL.

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

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

Annotations indicate read-only, idempotent, and non-destructive. Description adds behavioral details like walking the ladder, returning specific fields, and explaining basket partition handling. No contradiction.

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

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

Description is dense and front-loaded with purpose, but somewhat verbose. Could be more concise without losing key details. Structured with clear 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?

No output schema exists, so description fully covers returned fields for both modes (top_of_book, vwap_fill_price, slippage_pp, etc.) and addresses edge cases like thin legs and forced directional risk. Complete for tool complexity.

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

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

Schema coverage is 100%, so baseline 3. Description adds meaning beyond schema by explaining mode requirements (market vs event), default values, and interpretation of size_usd in basket mode as settlement notional. Significant added value.

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

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

The description clearly states 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It lists specific outputs and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly advises to use before acting on polymarket_arbitrage signals or trades above $500. Provides context on thin books and partial fills, but does not explicitly state when not to use it or alternatives.

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

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

Adds extensive behavioral context beyond annotations: explains compatibility_warning conditions, temporal_alignment, skipped_cross_type and skipped_cross_subtype counters. Clearly describes that both venues are queried and how spreads are computed. 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?

Front-loaded with purpose and modes, then covered details systematically. While lengthy, each sentence provides unique information. Slightly verbose but justified given the complexity of the tool.

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

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

Given no output schema, the description comprehensively covers return fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). Addresses edge cases (matched_pairs:0) and warns about temporal mismatches.

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 each parameter. The tool description further adds examples and explains the relationship between topic and explicit tickers, enriching the semantic meaning beyond the schema.

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

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

The description clearly states 'Cross-venue spread between Kalshi and Polymarket' with specific verb+resource. It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison and providing two modes (topic shortcuts and explicit tickers).

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

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

Detailed guidance on when to use topic mode vs explicit mode, including listing all 10 topic shortcuts. Warns that most pre-mapped topics return compatibility warnings and are not tradeable, but does not explicitly state when to avoid using the tool altogether.

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 and idempotentHint, which are consistent. The description adds context about scoping (anonymous IP, BYO key, account ID) and the ability to list all keys, which annotations do not cover.

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

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

Two sentences with no wasted words. The purpose is front-loaded and every sentence adds value.

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

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

For a simple tool with one optional parameter, the description fully covers retrieval, listing, scoping, and relationships with siblings. No output schema is needed given clear return intent.

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 'key'. The description adds the critical nuance that omitting the key lists all saved keys, which is not fully captured in 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 tool retrieves a value or lists all keys, with the verb 'retrieve' or 'list' and the resource 'memory'. It distinguishes from siblings 'remember' and 'forget' by naming them directly.

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

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

Provides explicit use cases (e.g., looking up target ticker, address, notes) and mentions pairing with remember/forget. However, it does not explicitly state when not to use or list alternatives beyond the named 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?

Adds context beyond annotations: describes mark_read side effect, return fields, filtering options, and polling suitability. Annotations already cover readOnly, openWorld, idempotent, and non-destructive, and description is consistent.

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

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

Three concise sentences with no filler. Front-loaded with purpose, then details, then usage note. Every sentence adds value.

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

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

No output schema, but description explains return fields adequately. All parameters described with behavior context. Annotations cover safety. Includes alternative access method. Complete for a read tool with optional filters.

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 full coverage (5 parameters), so baseline is 3. Description adds value by explaining mark_read's mutation effect, giving a concrete type example, and clarifying that since is ISO timestamp, improving usability beyond schema descriptions.

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

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

Clear verb ('Pull') and resource ('fired events from your subscription feed') with specific return fields listed. Distinguishes from siblings as there is no other alert-fetching 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?

States that polling works fine and provides an alternative REST endpoint for scripts/dashboards. Lacks explicit comparison to sibling tools or when-not-to-use guidance, but context is sufficient.

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

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

Discloses fan-out to multiple sources, fallback mechanism (GDELT→GNews), soft-fail for patents, return format with citation URIs. Annotations already indicate read-only, open-world, idempotent, non-destructive, and description adds further context without contradiction.

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

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

Description is informative but slightly lengthy; however, it is well-structured with examples and front-loads the main purpose. Every sentence adds value, though could be trimmed slightly.

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 covers return format (structured changes[], total_changes, citation URIs). It explains multiple data sources, fallback, and parameter formats. Comprehensive for a complex tool with three required parameters.

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 beyond schema by explaining that type is only 'company', since accepts ISO date or relative shorthand with examples, and value accepts ticker or CIK. This compensates well for the high schema coverage.

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

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

Description clearly states the tool returns a change feed for a company in a time window, covering SEC EDGAR filings, GDELT→GNews news, USPTO patents. It distinguishes from the sibling tool entity_profile by explicitly directing users there 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?

Provides explicit usage examples such as 'What's new with X' queries, and advises using entity_profile for static profile instead. Also describes when GDELT or GNews is used based on rate limits.

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

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

Beyond annotations (idempotentHint=true, readOnlyHint=false), the description adds key behavioral details: key-value scoping by identifier, persistence difference for authenticated vs anonymous sessions, and pairing with recall/forget. 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 concise (4 sentences) with a front-loaded main purpose. Every sentence adds value without redundancy or fluff.

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

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

Given no output schema, the description sufficiently covers behavioral aspects (storage, scoping, persistence) and usage context. It is complete for a simple write tool.

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

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

The schema already provides full descriptions for both parameters (key and value). The description adds minimal extra context (e.g., 'use when...'), but the schema bears the burden. Baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse, using a specific verb ('save') and resource ('data'). It distinguishes from siblings 'recall' and 'forget', making its 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?

The description explains when to use ('when you discover something worth carrying forward') with concrete examples. While it mentions related tools, it lacks explicit 'when not to use' guidance, slightly lowering the score.

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 read-only/idempotent annotations, the description adds valuable behavioral details: graceful degradation of LEI/FIGI enrichment, internal cascading through multiple endpoints, explicit 'unresolved' field behavior, and source labelling. These are not inferable from annotations alone.

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 front-loaded with practical examples and structured with SUPPORTED TYPES. Some redundancy exists (e.g., repeating input formats already in schema), but the detail is largely justified 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?

With no output schema, the description carries full responsibility for explaining return values. It covers both entity types, defines output components (CIK, ticker, LEI, FIGI, RxCUI, etc.), and documents failure/fallback behavior thoroughly, making it complete for an identifier-resolution tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning by explaining what each type returns (e.g., company returns CIK + ticker + LEI + FIGI; drug returns RxCUI + ingredient + brand) and reiterating accepted value formats, though much of this overlaps with schema descriptions.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with concrete examples like 'find the CIK for…' and 'what's the ticker for…'. It distinguishes itself from sibling tools by focusing on identifier resolution rather than profiles 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?

It explicitly instructs to 'Use FIRST whenever you have a name but need an ID' and notes it replaces 2-3 manual lookups. However, it doesn't name alternative tools for scenarios where an ID is already known or when deeper entity profiles are needed, leaving some ambiguity.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds detail: it probes each entity with ai_visibility_check, ranks results by score, and surfaces most/least recognized. 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?

Three sentences, no extraneous words. Front-loaded with purpose, then mechanism, then example use case. Every sentence adds value.

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

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

Despite lacking an output schema, the description clearly states the return value: 'ranked list with score, confidence, signal density per entity.' Covers all key aspects for an agent to use the tool effectively.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds extra context for the 'entities' parameter: 'First entry treated as the subject for narrative; rest are competitors,' which is not in the schema. This enriches the semantics.

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 'Compare AI visibility across multiple entities side-by-side,' using a specific verb ('compare') and resource ('AI visibility'). It distinguishes from sibling 'ai_visibility_check' by indicating it probes multiple entities and ranks them, and from 'compare_entities' by the AI-presence focus.

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 a concrete use case: 'competitive AI-marketing audits' with an example question. Implicitly contrasts with single-entity probe (ai_visibility_check). However, it does not explicitly state when not to use or list alternative tools.

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

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

The description goes beyond annotations by detailing fan-out behavior to two services, graceful degradation on partial failures, and a specific timing caveat ('bundlephobia's first measurement on a new version can take 5-30s'). There is no contradiction with the provided annotations (readOnly, idempotent, 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?

The description is information-dense but remains readable. Every sentence serves a purpose, covering use case, services queried, return structure, ecosystem scope, and failure behavior. It is slightly long but well-organized, justifying a 4 rather than 5.

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 enumerates return fields (summary block with is_latest, license, etc.), per-advisory details, links, alternative versions, and a sources_failed indicator for graceful degradation. The tool has only 2 parameters with no nested objects, so this is 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?

With 100% schema coverage, the baseline is 3. The description adds value by clarifying that version defaults to the latest when omitted and that scoped packages (e.g. '@types/node') are accepted, which supplements the schema descriptions. However, this added value is moderate, earning a 4.

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

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

The description clearly states the tool is a composite check for evaluating npm packages, specifying the exact services queried (deps.dev and bundlephobia) and the type of information returned (license, advisories, bundle size, etc.). It uses a specific verb-resource pair ('Scan Dependency') and distinguishes itself from sibling tools by focusing on npm dependency analysis.

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

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

The description explicitly states when to use the tool: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides clear guidance on ecosystem limitations ('NPM ecosystem only in v1') and directs users to alternative tooling for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). Additionally, it explains partial failure behavior gracefully.

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

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

Annotations already declare readOnlyHint, openWorldHint, etc. Description adds rich behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging, and offset for verification. No contradiction.

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

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

Well-structured, brief (~100 words). Front-loaded with the main action, then use case, then technical details. Every sentence adds value with 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?

Covers return format (top-N passages with offsets and similarity scores), cap and truncation, and pairing with sibling. Could mention error handling or what 'flagged' means, but overall complete for a non-output-schema tool.

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

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

Schema description coverage is 100% (all 3 parameters have descriptions). The description reinforces the schema with context but adds minimal new parameter-specific information beyond what the schema already provides.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific examples (SEC 10-K body, article). It distinguishes from sibling tools by explicitly pairing with ask_pipeworx_grounded and explaining when to use this tool over alternatives.

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

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

Provides explicit guidance: 'Use when the record is too big to cram into the prompt' and explains pairing with ask_pipeworx_grounded. Does not explicitly list when not to use, but the context is clear and helpful.

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: it specifies the need for an OAuth account, explains the always-on feed, details optional delivery channels with constraints (SMS cap, webhook auto-disable after 10 failures), and notes the one-time return of the webhook signing secret. The annotations (readOnlyHint=false, idempotentHint=true, etc.) are consistent and the description enriches them with critical operational details.

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

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

The description is front-loaded with the main purpose and state-of-the-world requirement (OAuth account). It is verbose but information-dense; every sentence adds value. It could be slightly more concise, but the structure is clear and logical.

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

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

Given the complexity of the tool (multiple subscription types, delivery channels, constraints), the description is thorough. It covers required authentication, type-specific parameters, delivery options, and limitations (SMS cap, webhook failure handling). No output schema is provided, but the description mentions the return of subscription id and webhook secret, which is sufficient for invocation.

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

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

The input schema has 100% coverage with descriptions for all parameters, but the tool description adds significant meaning: it explains type-specific param structures (e.g., sec_8k items, polymarket_edge topic), delivery requirements (e.g., phone verification for SMS), and webhook signing details. This goes beyond what the schema provides, though the schema already enumerates the fields.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It uses specific verbs ('Create') and identifies the resource ('subscription'), effectively distinguishing it from siblings like 'unsubscribe' 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?

The description provides context for when to use the tool, including the requirement for a Pipeworx OAuth account and explicitly listing supported subscription types and delivery channels. However, it does not explicitly state when not to use it or mention alternatives beyond the sibling tools. This is clear but lacks explicit exclusion criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds context: returns category-bucketed examples drawn from live catalog, and behavior with/without topic argument. No contradictions.

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

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

Description is moderately long but well-structured. Alternative phrasings, return description, and usage instructions are all present without unnecessary repetition. Each sentence adds value.

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

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

Given no output schema, description adequately explains return format (category-bucketed examples with tool+argument shapes). Complete for an onboarding tool; missing specifics like number of examples per category is acceptable.

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 (one optional topic). Description adds specific topic values and clarifies that omitting topic gives a cross-category spread, adding meaning beyond 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 tool returns category-bucketed example questions with exact tool and argument shapes, serving as an onboarding entry point. It distinguishes from siblings like ask_pipeworx and discover_tools by focusing on suggesting questions rather than answering or discovering tools.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Indicates when to use and effect of optional topic parameter. Does not explicitly mention 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?

Adds ownership enforcement and deactivation behavior beyond annotations. No contradiction with annotations (idempotentHint, destructiveHint).

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

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

Two sentences, no fluff, front-loaded with action. Every sentence adds value.

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

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

Covers key aspects: action, ownership, deactivation. Lacks return value details, but sufficient for the simple, idempotent mutation.

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?

Adds value by referencing that the id comes from subscribe, reinforcing parameter origin. Schema already provides description, so baseline 3 is surpassed.

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 'Cancel a subscription by id' with ownership enforcement and deactivation behavior. Distinguishes from siblings like subscribe and list_subscriptions.

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

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

Specifies ownership enforcement ('only cancel your own subscriptions') and deactivation vs deletion, guiding appropriate use. Lacks explicit exclusions 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?

Even with readOnlyHint, openWorldHint, and idempotentHint already provided, the description adds crucial behavioral detail: the exact verdict vocabulary, the meaning of could_not_verify (with verification_error and "must not be shown as one"), and the distinction between unsupported and could_not_verify. It also discloses the routing behavior and citation format, going well beyond the annotations.

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

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

The description is longer than average, but the opening query phrases immediately signal scope, followed by the purpose and key routing logic. The later error-semantics paragraph is essential and not redundant. A slight trim of the "grounded pipeline…then judged" phrasing could tighten it, but it remains well organized.

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

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

With no output schema, the description fully compensates by enumerating the returned verdict types, the evidence/citation, reasoning, and the error payload for could_not_verify. It also covers both input parameters and explains what unsupported vs could_not_verify mean. For a tool of this complexity, the description is 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?

Although schema coverage is 100%, the description enriches both parameters. It explains that tolerance_pct overrides the claim-wording default, is capped at 5, and recommends 1–2 for hallucination detection. It also gives realistic claim examples, so the caller understands what a valid claim looks like.

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

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

The description opens with concrete natural-language triggers ("Is it true that…", "fact check", "verify the claim that…") and explicitly states the tool's job: natural-language claim verification against authoritative sources. It distinguishes the structured SEC EDGAR path for company-financial claims from the grounded pipeline for all other factual claims, which separates it from sibling research or AI-visibility tools.

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

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

It gives clear usage direction: "Use whenever the agent needs to check whether something a user said is factually correct." It also explains that company-financial claims take the structured path and all other claims fall through to the grounded pipeline, and states the tool replaces multiple sequential calls. It does not explicitly name when-not-to-use alternatives, but the guidance is unambiguous for the core use case.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds the constraint that all three location parameters (lat, lon, address) are required, which is useful but not beyond what annotations already convey about safety. No additional behavioral traits are disclosed.

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 plus an illustrative example. The key purpose is front-loaded, and every sentence adds value. No unnecessary words.

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

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

Given the tool's simplicity, with 6 parameters fully described in schema and annotations covering safety, the description is mostly complete. It explains the core functionality and the critical requirement for all three location fields. However, it does not describe the structure of the response (e.g., format of scores and description), which would be helpful since no output schema exists.

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

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

Schema coverage is 100% with detailed descriptions for each parameter. The description goes further by explaining the relationship between coordinates and address: 'the coordinates locate the point and the address disambiguates it.' This adds semantic value that helps the agent understand why all three are needed.

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

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

The description clearly states the tool returns Walk/Transit/Bike scores (0-100) plus a human-readable description. It uses specific verbs and resources, and the purpose is distinct from all sibling tools, which focus on other domains like research or entity 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?

The description includes a NOTE that lat, lon, and address must all be provided, and gives an example. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it. Since no sibling tools offer similar functionality, this is a minor gap.

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