Gnews

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds behavioral details: it probes specific models, returns per-model results with scores/confidence/signals, and explains payment implications for the Anthropic model. No contradiction.

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

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

The description is a single, well-structured paragraph. It front-loads the main action, then details parameters, then use cases. No redundant sentences; every sentence earns its place.

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

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

Given the tool has 4 parameters with full schema coverage and no output schema, the description compensates by describing the return structure (per-model score, confidence, signals, raw_response + combined view). It is complete for an agent to understand inputs and outputs.

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 defaults ('Default model is Workers AI Llama-3.3-70b (free)'), and usage patterns (e.g., pass _apiKey for Anthropic). It enriches understanding beyond schema.

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

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

The description clearly states the tool probes LLMs for brand visibility and scores it (0-100). It specifies the default model and the optional Anthropic integration. Though it doesn't explicitly differentiate from sibling tools, its purpose is uniquely defined.

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 mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not provide when-not-to-use or compare to alternatives, but the context is clear enough for an agent to decide.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds useful contextual behaviors: it routes across many tools, returns stable pipeworx:// citation URIs, works on every tier, and is a single 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 longer than average but well-front-loaded with the key 'PREFER OVER WEB SEARCH' directive followed by concrete examples and escalation paths. It is structured effectively, though some redundancy in examples 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?

Given the tool's complexity and lack of an output schema, the description thoroughly covers what the tool does, when to use it, what it returns (structured answer with citations), and how it relates to sibling tools. It includes concrete examples and addresses the default entry point.

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 six parameters documented as aliases for the same 'question' field. The description itself adds little parameter-specific detail beyond natural language phrasing, so it meets the baseline but does not exceed it.

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

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

The description clearly states the tool's function: it routes questions to one of 5,529 tools across 1,455 sources and returns a structured answer. It also distinguishes itself from siblings by explicitly contrasting with ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit usage guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with specific alternatives for grounded answers and deep research. It also lists example query types and use cases.

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

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

Despite annotations already indicating read-only and idempotent behavior, the description adds significant context: beta status, live candidate testing, current no-candidate state, and clarification that it is a fully working router rather than a fallback. This goes well beyond the annotations and provides a transparent behavioral profile.

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

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

The description is four sentences, each providing essential information: the beta identity, current state, usage guidance, and a note on its functional completeness. It is front-loaded with the most important facts and contains 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?

The description fully explains the tool's relationship to ask_pipeworx, its current behavior (identical), and how to use it. Even without an output schema, the reference to the same response shape as ask_pipeworx covers return expectations, making the description complete for this context.

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

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

The input schema has 100% description coverage for all 6 parameters (all aliases for 'question'), so the description's lack of parameter details is acceptable. It does not add any extra semantics beyond the schema, thus the baseline score of 3 applies.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape, but with candidate routing improvements. It distinguishes itself from the sibling ask_pipeworx by emphasizing its experimental routing edge and current inactive state.

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 instructs to use it exactly like ask_pipeworx when the newest routing is desired, and mentions that results are compared against the stable router. This names the alternative and provides a clear condition for use, fulfilling the 'when/when-not/alternatives' criterion.

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

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

Annotations already mark it read-only, open-world, idempotent, and non-destructive, but the description adds rich behavioral detail: it returns evidence as a verbatim quote, provides confidence and source, and specifies five refusal reasons including 'data_truncated' and 'no_tool_match'. It also discloses the extra LLM call cost, which is beyond what annotations convey.

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

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

Although the description is longer than minimal, every sentence serves a purpose: stating the core purpose, explaining the routing and extraction process, describing the return format and refusal reasons, giving usage guidance, and noting the cost trade-off. It is front-loaded with the primary function and well-structured.

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

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

For a tool with no output schema, the description fully specifies the successful return shape and failure modes, including refusal reasons. It also explains when to use it versus the sibling ask_pipeworx, covering both usage context and cost implications. No critical context 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?

The input schema covers all six parameters with descriptions, all being aliases for 'question', so schema coverage is 100%. The description does not add parameter-specific syntax or examples; it only mentions filling arguments generically. Baseline 3 is appropriate because the schema already handles parameter 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 identifies this as a 'hallucination-resistant answer mode for high-stakes reads' and explains its mechanism: it routes like ask_pipeworx, fetches data, and extracts the answer only from the tool result. This differentiates it from the sibling ask_pipeworx by emphasizing grounded, evidence-backed answers.

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

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

Explicit guidance is given: use when the answer will be 'quoted, cited, or acted on' and facts must not be invented. It also states a cost trade-off and recommends preferring ask_pipeworx for casual lookups, making the choice between siblings clear.

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

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

The description extensively covers behaviors beyond annotations: fan-out logic, response shapes, resolver contract, parent event extraction, news fallback handling, safety mechanisms (low-confidence short-circuit, closed markets, wide spread), and resolution-rule risk. No contradiction with annotations.

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

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

The description is detailed but every sentence serves a purpose. It is front-loaded with the core purpose and then expands into specifics. Although lengthy, it remains organized and informative without unnecessary 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?

For a tool with no output schema, the description is remarkably complete. It covers input variations, processing logic, response structure, error states, edge cases, and safety checks. No gaps remain for agent understanding.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning for all three parameters: explains 'market' accepts slug/URL/question text, 'depth' enum options and defaults, and 'include_raw' purpose. Adds value beyond schema.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data. It specifies the verb ('Research'), resource ('Polymarket bet'), and scope ('in one call'), distinguishing it from sibling tools like 'polymarket_arbitrage' or 'validate_claim'.

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

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

Explicitly states when to use ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides examples of fan-outs for different bet types. Lacks explicit when-not-to-use or alternatives, but the context is clear.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds details: for companies, it pulls latest 10-K data from SEC EDGAR/XBRL with proper off-calendar handling; for drugs, FAERS adverse-event counts. It also mentions sorted results and citation URIs.

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 thorough but slightly long. However, it is well-structured with usage examples front-loaded and each sentence providing necessary information. Minor redundancy could be trimmed, but overall clear.

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

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

Given the annotations and input schema, the description fully explains the tool's capabilities: input requirements, data sources, handling of fiscal years, output format (paired data + citation URIs). No output schema exists, but the description sufficiently covers return values.

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

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

Schema coverage is 100%, but description adds meaning beyond enum values: 'company' yields revenue+net income+cash+debt; 'drug' yields FAERS counts, FDA approvals, trial counts. It explains values format (tickers/CIKs for companies, names for drugs) and limits (2-5 items).

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific verb phrases like 'compare', 'X vs Y', 'rank these companies'. It distinguishes from sequential single-pack lookups.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It explains what each type (company/drug) returns, providing clear context for when to use. Does not specify when not to use, but alternatives are implicit.

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 convey read-only, idempotent, non-destructive, and open-world nature. The description adds significant behavior: account requirements, depth tier differences, parallel tool routing, findings packet structure (verbatim evidence, confidence, source, fetched_at, citation), gaps[] that are never invented, second-hop iteration, contradictions[], semantic excerpting, and latency ranges. It greatly enriches the annotation baseline with no contradiction.

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

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

The description is very long and dense, with no visual structure like bullet points or sections. Nearly every sentence carries unique, valuable information, so it is information-efficient, but the single-paragraph format makes it harder for an agent to parse quickly. A structured layout would improve conciseness.

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

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

Despite lacking an output schema, the description comprehensively explains return values (findings packet), gap handling, contradictions, citation URIs, hop semantics, and expected latencies. It covers prerequisite (account), alternatives, and behavioral nuances, making it complete for a complex tool.

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

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

Schema coverage is 100%, providing solid baseline. The description adds extra nuance: depth values map to specific facet counts and hop behaviors, 'thorough' requires a paid plan, and the 'question' parameter is illustrated with examples and the notion of broad/multi-part queries. This is meaningful added value beyond the schema, though not fully exhaustive.

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 Pipeworx's structured data sources, decomposing questions into facets and routing to tools in parallel. It explicitly distinguishes itself from open-web search and sibling tools like ask_pipeworx ('this is NOT open-web search', 'For a single lookup use ask_pipeworx'), so purpose is unambiguous and differentiates from 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?

Explicit when-to-use guidance is provided: 'Best for broad/multi-part questions over structured data' with concrete examples, and clear directives to use ask_pipeworx for single lookups, breaking news, or colloquial topics, and when not signed in. This gives the agent actionable selection criteria 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 already indicate readOnlyHint=true and idempotentHint=true. The description adds valuable context: returns top-N tools with full schemas and curated examples, ready to call directly without further lookups. 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 that front-loads the purpose. While slightly long, every sentence adds value, covering domains, behavior, and usage guidance. Could be slightly more concise but well-structured.

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

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

Given the tool's complexity (6 params, no output schema), the description adequately explains what it does and returns. It mentions return format (names, descriptions, schemas) and provides examples. Lacks details about pagination or sorting but sufficient for a discovery tool.

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

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

Schema coverage is 100% with descriptions. The description adds value by explaining the query parameter with examples and listing aliases (task, q, description, search). This goes beyond the schema's basic descriptions.

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

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

The description clearly states it's for discovering tools by describing the data or task. It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools by being a meta-tool that returns tool definitions.

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 'Call this FIRST when you have many tools available', and describes when to use: 'browse, search, look up, or discover what tools exist'. Provides clear guidance on its role in the workflow.

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, destructiveHint. Description adds context: fans out across multiple sources, soft-fails for patents, returns specific fields. No contradictions, adds meaningful behavioral 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?

Well-structured: starts with examples, then details. A bit lengthy but every sentence adds value. Could slightly tighten but appropriate for 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?

No output schema, but description thoroughly explains return fields (cik, company_name, recent_filings with URIs, fundamentals, etc.). Covers all user needs for a profile 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 type enum and value string. Description adds examples ('AAPL', '0000320193'), emphasizes name not supported, and repeats required format. Adds value beyond schema.

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

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

The description specifies the exact purpose: 'full cross-source profile of a US public company'. It uses clear verb-noun pairs and provides many example queries, distinguishing it from siblings like compare_entities and resolve_entity.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and 'Names not supported — use resolve_entity first' giving clear when-to-use and 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 provide destructiveHint=true and idempotentHint=true; description restates deletion but adds no additional behavioral context beyond what annotations indicate.

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 essential information front-loaded; 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?

Tool is simple with one parameter and no output schema; description fully covers its purpose and usage.

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

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

Schema coverage is 100% for the single parameter 'key', with straightforward schema description; description adds no extra meaning beyond schema.

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

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

Clearly states verb 'Delete' and resource 'previously stored memory by key', distinguishing it from siblings 'remember' and 'recall'.

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

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

Explicitly provides when to use (stale context, task done, clear sensitive data) and pairs with remember and recall, offering clear 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?

Description adds behavioral context beyond annotations: it fetches the page, extracts title/description/key links, and emits standard markdown. Annotations already indicate read-only, idempotent, non-destructive nature, so description complements without contradicting.

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, front-loaded with the main purpose, no wasted words. Efficiently covers what, how, and why.

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 low complexity, complete schema coverage, and no output schema, the description fully explains the output (single text blob) and the process. No missing information for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters. Description mentions 'Full URL' and 'max number of link entries' but adds no new semantic details beyond what the schema provides. Baseline 3 is appropriate.

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

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

Clearly states it generates an llms.txt file for a URL, specifying the action (generate), resource (llms.txt), and what it extracts (title, description, key links). Distinguished from 43 sibling tools, none of which have similar functionality.

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

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

Lists concrete use cases: indexing a client's site, drafting your own project's llms.txt, or auditing a competitor. Does not explicitly state when not to use or suggest alternatives, but the use cases are clear and contextually appropriate.

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

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

Description adds return fields beyond annotations, which already declare read-only and non-destructive behavior. No contradictions; adds useful behavioral context.

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

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

Two sentences, no redundancy. First sentence states purpose and return data; second sentence gives usage guidance. Very concise and well-structured.

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

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

For a simple list tool with one optional parameter, the description fully covers purpose, return values, and usage context. No output schema, but fields are listed.

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

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

Schema covers the single optional parameter fully. Description mentions 'active subscriptions' implying default exclusion of inactive, but does not add new meaning beyond the schema.

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

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

Clearly states 'List the caller's active subscriptions', specifying verb, resource, and scope. Distinguishes well 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?

Explicitly advises using this to review subscriptions before adding more or to find an id to cancel, providing clear usage context. Does not explicitly state when not to use, but the guidance is strong.

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

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

Annotations are all false, providing minimal inherent signal, but the description richly compensates by disclosing rate limiting ('Rate-limited to 5 per identifier per day'), zero quota impact, daily team reading cadence, roadmap influence, and the claim_token lifecycle (returns a token, can be used later to check resolution). No contradictions with annotations exist.

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

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

The description is front-loaded with the core purpose, then logically progresses through use cases, boundary conditions, message guidelines, claim-token flow, impact, rate limits, and cost. Every sentence contributes distinct, non-redundant information; there is no filler or repetition.

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 effectively explains the claim_token response and follow-up flow, as well as rate limits and cost. A minor gap is that it states the no-account case returns a claim_token but does not explicitly describe what happens when an account is present, though this is unlikely to confuse an agent. Overall, it is sufficiently complete for the tool's simplicity.

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

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

The schema already provides 100% coverage for all four parameters with detailed descriptions, so the baseline is 3. The description adds workflow-level context: it clarifies the 'message' parameter with formatting rules (reference Pipeworx tools, not user prompts), explains 'type' through real-world scenarios, and offers a concrete example of 'claim_token' usage ('pipeworx_feedback({claim_token:"pwfb_…"})'). This exceeds the schema's literal explanation.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which is a specific verb+resource pairing. It then enumerates concrete use cases (bug, feature/data_gap, praise) and explicitly differentiates the tool from other MCP servers' feedback channels, making its purpose unmistakable.

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

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

It gives explicit when-to-use guidance ('Use when a tool returns wrong/stale data (bug)...') and when-not-to-use ('if the tool came from a different MCP server... file it with that server instead'). It also provides content-formatting instructions ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and the claim_token follow-up workflow, making this a complete usage guide.

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

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

Discloses data source (CF analytics-engine), privacy (no PII), and caching (5min-1h). Aligns with annotations (readOnly, idempotent, openWorld, non-destructive).

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

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

Two sentences plus bullet list. Front-loaded with main output. Every sentence adds value with no redundancy.

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

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

Despite no output schema, description sufficiently explains return values (top tools, packs, volume). Annotations and simple parameter make this 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 already covers the single enum parameter with description. Description adds no new semantic beyond reinforcing use case, which is adequate given 100% 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?

Clearly states it returns 'top tools, top packs, and total call volume' over a window. Distinguishes from siblings by focusing on aggregated usage signals rather than individual 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 three explicit use cases and guidance on window selection (shorter for hot, longer for steady-state). No explicit when-not, but implied context.

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

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

Discloses internal logic including Jaccard similarity, partition filter, and fill check. Annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent; description adds detailed behavioral context beyond annotations.

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

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

Well-structured with clear sections and bullet points, but somewhat verbose. Could be slightly more concise while retaining all essential information. Front-loaded with main purpose.

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

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

Despite no output schema, the description fully explains the response structure, including fields for opportunities, partition check, and fill check. Covers all necessary context for a complex arbitrage detection tool.

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

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

Schema coverage is 100%, and the description enriches each parameter with usage examples (e.g., event slug format, topic seed question) and explains the effects of each mode, 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by detailing its unique scanning and checking logic.

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

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

Provides explicit when-to-use guidance for each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. Also includes when-not-to-trade advice based on fill check results and recommends polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true. The description adds extensive behavioral context: it explains the three segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) with technical details, response structure (by_segment, diagnostics), caching (1h at KV level), and edge calculation intricacies. No contradictions with annotations.

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

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

The description is quite long and dense, with multiple paragraphs explaining segments and parameters in great detail. While it front-loads the core purpose, the technical elaboration could be more concise. It is structured but verbose, earning a mid-range score.

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

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

Given no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics) and key fields (edge_pp_net, kelly_fraction, market.liquidity, etc.). It also covers caching, segment conditions, and parameter interactions, making it complete for an agent to understand what the tool returns.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds conceptual context (e.g., 'Tradeable-edge knobs') but does not significantly enhance understanding beyond what the schema already provides. It explains the models behind parameters but does not add new semantic details for individual parameters.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb ('scan') and resource ('Polymarket markets'), and distinguishes itself from sibling tools by detailing its unique approach (three segments, Pipeworx data). This makes it unambiguous for an AI agent to select.

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 frames the tool for 'what should I bet on today' and mentions that agents 'discover opportunities without paging hundreds of markets.' While it provides clear context, it lacks explicit mention of when not to use it or direct comparisons to siblings like polymarket_arbitrage or polymarket_edge_tracker, which could be 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 confirm read-only, idempotent, non-destructive. The description adds detailed return structure (tracked, expired, snapshot_dates), explains edge_pp_net signing, decay computation from daily closes, and snapshot gaps. 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 lengthy but well-structured: starts with a summary, then details response fields and limits. Every sentence adds value, though some brevity could be improved without losing clarity.

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

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

No output schema exists, so the description fully explains return fields (tracked, expired, snapshot_dates) and their subfields (trend, decay, lifespan). It also covers limitations and data gaps, making it complete for agent 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 covers 100% of parameters. Description adds default values (days=14, window='1wk'), explicit options for window, and clamp range for days. Also describes the response structure in detail, adding meaning beyond schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily polymarket_edges snapshots. It answers a specific question about edge duration and shrinkage, distinguishing itself from single-snapshot tools like polymarket_edges.

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

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

The description explains the use case (analyzing edge persistence over time) and contrasts with a fresh vs old edge. It provides limits (60-day TTL, snapshot availability) but does not explicitly list alternatives or when not to use.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds significant behavioral context: walking order-book ladder, returning verdicts (clean/degraded/cannot_fill), per-leg details, and identifying forced directional risk. No contradictions with annotations.

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

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

The description is lengthy but well-structured with bold headers for modes. Every sentence adds value, explaining return fields and edge cases. Minor improvement could be more compact, but given complexity it is efficient.

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

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

Despite lacking an output schema, the description enumerates all return fields for both modes, including edge cases like thin_legs and forced_directional_risk. It covers usage constraints, behavioral traits, and error states, making it self-contained for agent 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%, but the description adds substantial meaning beyond schema descriptions. For each parameter it explains mode-specific interpretations (e.g., size_usd meaning for single-market vs basket), defaults, and constraints (clamp 10–1,000,000). Side parameter explains mode-dependent defaults and enum values.

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: checking realizable-vs-theoretical edge against live CLOB order-book depth. It distinguishes between single-market and basket modes, and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) to differentiate when to use this tool.

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

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

The description provides explicit guidance: use this tool before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. It explains why (theoretical overround not capturable, partial fills create unhedged positions) and gives clear context for 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 set readOnlyHint=true, which aligns with the query-only nature. The description adds rich behavioral context: response structure, safety fields, compatibility_warning conditions, and temporal_alignment. 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 lengthy but well-structured with clear sections (purpose, modes, response, safety fields). Every sentence adds value; no fluff. Slightly verbose but justified by complexity.

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

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

Despite no output schema, the description thoroughly explains return fields (leg-by-leg prices, spread array, compatibility_warning, temporal_alignment, skipped counters). Complete coverage for a query tool.

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

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

Schema coverage is 100%, and the description adds significant meaning: explains the topic list values, how explicit parameters override topic, and provides examples.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description explicitly explains two modes (topic shortcuts and explicit tickers), provides when-to-use guidance, and warns when spreads are not meaningful via compatibility_warning fields.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable context: scoping to identifier (IP, key hash, account ID) and pairing with remember/forget, which goes beyond annotations.

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

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

The description is concise, with three sentences that front-load the main purpose, then add context and companion tool references. No wasted words.

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

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

For a simple tool with one optional parameter and no output schema, the description covers retrieval, listing, scoping, and lifecycle (pair with remember/forget). It is completely adequate for the complexity.

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

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

Schema coverage is 100% with a description for the key parameter. The description adds meaning beyond schema by explaining the behavior of omitting the key (listing all) and providing example use cases.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys when omitted. It provides concrete examples (target ticker, address, research notes) and distinguishes from siblings remember and forget.

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

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

The description explains when to use the tool (look up context stored earlier, avoid re-deriving) and how to use it (omit key to list all). It mentions companion tools remember and forget, but does not explicitly state when not to use it.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by explaining mark_read behavior ('flag returned events read so the next call only shows newer ones') and that the feed is persisted. This goes beyond the annotations without contradiction.

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

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

The description is concise, with the key action in the first sentence. It covers purpose, output fields, filtering, mark_read effect, and alternative access in just a few sentences without redundancy.

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

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

Despite no output schema, the description lists key return fields (source, citation_uri, raw payload). It explains filtering by type and since, and the mark_read option. However, it omits mention of 'limit' and 'unread_only' parameters, though these are well-described in the schema. Overall, it provides sufficient context for a read-only 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% for 5 parameters. The description reinforces 'type' and 'since' usage with examples like 'sec_8k' and ISO timestamp. It explains the behavioral effect of mark_read on subsequent calls, which adds context not present in the schema description alone.

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

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

The description starts with 'Pull fired events from your subscription feed' which clearly states the verb (pull/returns) and resource (alerts from subscription feed). It explains the output includes source, citation_uri, and payload, setting it apart from sibling tools like list_subscriptions or search_news.

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

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

The description provides guidance that polling works fine and mentions an alternative direct API endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool or compare it to other sibling tools like ask_pipeworx or search_news.

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 parallel calls, fallback logic, soft-fail for USPTO, and output format. Annotations already indicate safety, but description adds behavioral depth.

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?

One efficient paragraph front-loading examples and purpose. Dense but no wasted words. Minor room for tighter phrasing.

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

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

Covers purpose, usage, parameters, return format, and alternative tool. No gaps given schema coverage and annotations.

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

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

Schema already describes all 3 parameters; description adds guidance on since formats and typical use, plus clarifies type and value formats.

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+resource: 'change feed for a company in the last N days/weeks/months'. Examples ground the tool. Explicitly distinguishes from sibling entity_profile.

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 when to use and when not ('use entity_profile instead'), gives parameter suggestions ('Use "30d" or "1m"'), and explains fallback behavior.

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

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

Annotations provide idempotentHint: true, which is consistent. The description adds valuable behavioral context: retention policy (persistent for authenticated users, 24 hours for anonymous), which goes beyond annotations. No contradictions.

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

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

The description is concise and front-loaded with the primary action. Every sentence adds value: purpose, usage examples, pairing with other tools, and retention details. No wasted words.

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

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

Given the tool's simplicity (2 required params, no output schema), the description covers all necessary aspects: purpose, when to use, how it works (key-value, scoped, retention), and relationships with siblings. It is complete for an agent to understand and invoke correctly.

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

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

Schema coverage is 100% with parameter descriptions. The description does not add new meaning beyond the schema for each parameter, so baseline 3 is appropriate. It repeats the purpose but doesn't add deeper 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 the tool's purpose: 'Save data the agent will need to reuse later.' It specifies the key-value pair storage mechanism and scoping by identifier. It also distinguishes itself from sibling tools like recall and forget by mentioning they are paired with this tool.

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

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

The description provides explicit usage guidance: 'Use when you discover something worth carrying forward' and gives concrete examples like resolved ticker, target address, user preference. It does not explicitly state when not to use, but the context is clear enough.

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

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

Beyond the annotations, the description discloses that the tool cascades through multiple endpoints, labels identifiers with their source, explicitly reports unresolved identifiers, and degrades gracefully if GLEIF/OpenFIGI are unavailable. It also states the call replaces 2-3 manual lookups, giving a complete picture of behavior.

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 clear examples and a structured breakdown by supported type. Some redundancy exists (e.g., listing examples and then repeating in type details), but every sentence contributes useful information.

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

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

For a tool with no output schema and moderate complexity, the description is remarkably complete. It explains the return format (identifiers with source labels, unresolved list), covers edge cases (network degradation), and provides enough context for an agent to select and invoke it correctly.

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

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

The schema already covers both parameters with descriptive text, but the description adds meaningful semantics by detailing what each entity type accepts (ticker, CIK, name for company; brand/generic for drug) and what outputs to expect (CIK, ticker, LEI, FIGI, RxCUI). This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool resolves a user-spoken name to canonical/official identifiers required by other tools. It gives specific examples ('ticker for…', 'CIK for…') and names the supported entity types, distinguishing it from siblings that likely consume these identifiers.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It doesn't name specific alternatives, but the context that other tools require these IDs implicitly establishes when not to use it (when you already have an ID).

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, no destructive behavior. The description adds behavioral details beyond annotations: it explains that the tool 'Probes each entity (your brand + N competitors) with ai_visibility_check, ranks by score, surfaces which is most/least recognized.' This provides context on the internal workflow without contradicting annotations.

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

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

The description is three sentences, all front-loaded with the core purpose. Every sentence adds value: first states purpose, second explains process and use case, third details output format. No fluff or repetition.

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 specifies the return: 'ranked list with score, confidence, signal density per entity.' Given the tool's complexity (comparing multiple entities, ranking), this is sufficient for an agent to understand what to expect. The description is complete for the tool's purpose.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning beyond schema: it explains that the first entity is treated as the 'subject' for narrative, and that context is shared across probes. It also mentions available models. This elevates the score above baseline.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare), resource (AI visibility), and distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (general comparison). The example question 'does Claude know about us as well as our competitors?' reinforces the purpose.

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

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

The description provides usage context: 'Useful for competitive AI-marketing audits' and gives an example question. It explains the internal process (probes each entity via ai_visibility_check, ranks by score). However, it does not explicitly state when not to use this tool versus alternatives like ai_visibility_check, so it's slightly lacking in exclusion guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: the composite nature, sources (deps.dev, bundlephobia), possible timeouts (5-30s for first bundlephobia measurement), and graceful degradation. 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 somewhat lengthy but well-structured, front-loading the main purpose followed by details. Every sentence adds value, though it could be slightly more concise without losing information.

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

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

No output schema exists, so the description must explain return values. It thoroughly lists the return fields (summary block, advisories, links, versions) and describes partial failure behavior. For a 2-parameter tool with no output schema, this is highly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds that scoped packages are accepted and version defaults to latest, but these are minor additions. The description does not provide much extra 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 it is a composite check for evaluating npm packages, covering license, advisories, version history, and bundle size. It distinguishes from siblings by being specific to npm dependency scanning, and the verb 'scan' plus resource 'dependency' is specific.

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

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

The description explicitly recommends use when an agent asks about safety, popularity, or size of a package. It also notes limitations (NPM only, partial failures). However, it does not explicitly mention when not to use or list sibling alternatives for other ecosystems.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the agent knows this is a safe, idempotent read operation. The description adds context on returned fields and filters, which is helpful but not extensive. It does not disclose pagination behavior or rate limits, which are partly covered by the schema's 'max' parameter.

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

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

The description is extremely concise: two sentences that cover purpose, return fields, and filters. No wasted words. Every sentence adds value.

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

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

Given the rich annotations, complete schema, and presence of an output schema, the description is adequately complete. It covers the core functionality and return format. A slight gap is that it does not explicitly state it requires an API key, but that is evident from the required parameters in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal additional meaning beyond the schema: it mentions 'content snippet' (though not explicitly in schema descriptions) and confirms supports for language/country filters. The examples in the schema already provide usage context.

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: searching global news articles by keyword. It specifies what is returned (title, description, content snippet, source, publication date) and the available filters (language, country). This distinguishes it from sibling tools like 'top_headlines' or 'deep_research', which serve different purposes.

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

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

The description provides clear context for when to use this tool (searching news by keyword) but does not explicitly state when not to use it or mention alternatives. It implies its usage through the verb 'search' and the mention of filters, but lacks explicit exclusions or comparison to siblings.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false; the description adds behavioral details like truncation at 200K chars, BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, and flagging of truncated inputs, far exceeding annotation coverage.

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

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

The description is efficient with front-loaded purpose: first sentence states core action. Subsequent sentences add usage guidance and technical details without redundancy. Slight room for tighter phrasing, but overall well-structured.

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

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

Given no output schema, the description fully explains return format (top-N passages with character offsets and similarity scores), constraints (200K char cap with truncation flag), and pairing with other tools, making it complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value with examples for the query parameter ('supply-chain risk', 'fiscal year 2024 revenue') and clarifies the text parameter as 'document text to search inside', enhancing 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 'Semantic search INSIDE a fetched record' using specific verbs and resource. It contrasts with fetching whole documents and mentions a sibling tool 'ask_pipeworx_grounded', distinguishing its purpose.

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

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

The description explains when to use: 'when the record is too big to cram into the prompt' and 'search_within saves context'. It also suggests pairing with 'ask_pipeworx_grounded'. However, it lacks explicit 'when not to use' instructions.

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

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

Description adds rich behavioral details beyond annotations: delivery channels, caps (10/day SMS), webhook auto-disable, signing secret. Consistent with annotations (idempotentHint=true, etc.). No contradictions.

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

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

Front-loaded with main action and prerequisite. Content is well-structured but slightly lengthy. Every sentence provides 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 types, delivery options, prerequisites), the description is comprehensive. Covers account requirement, type-specific params, delivery constraints, and return value. No output schema needed.

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

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

Schema coverage is 100%, but description adds significant meaning with examples for each type and detailed delivery explanations. For instance, it explains the semantics of sec_8k items and polymarket_edge topic.

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

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

The description clearly states the verb ('Create') and resource ('proactive monitoring subscription'), and distinguishes from siblings like list_subscriptions and unsubscribe. It provides specific details about what the tool does and its output.

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 prerequisite: requires Pipeworx OAuth account. Lists supported types with examples. Does not explicitly state when not to use, but the requirement and type details provide clear context.

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

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

The annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds value by explaining that the tool returns 'category-bucketed example questions' with exact tool and argument shapes, drawn from a live catalog. This provides behavioral context beyond what annotations offer, though it could mention that no state changes occur.

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

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

The description is detailed but slightly verbose. It front-loads common user questions and then explains the output structure, which is good. However, it could be more concise by removing some redundancy (e.g., listing all categories twice). Still, every sentence contributes to clarity.

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

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

Despite having no output schema, the description explains the return format (category-bucketed examples with tool + argument shapes). It covers the purpose, usage, optional parameter, and edge cases. For a simple tool with one optional parameter, this is complete and leaves no ambiguity.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by listing example topic values ('finance', 'pharma', etc.) and clarifying that omitting the topic gives a cross-category spread. This guidance helps an AI agent choose the right input.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions. It uses common user queries ('what can I ask Pipeworx?', 'give me ideas') and lists the categories, making the purpose unmistakable. It distinguishes itself from siblings by being the first tool to call when unfamiliar with Pipeworx's capabilities.

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

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

The description explicitly states to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and also covers optional topic filtering. It does not explicitly mention when not to use it or alternatives, but the context provided is sufficient for an AI agent to understand the primary 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, so the description's mention of 'fetch' is consistent. It adds that the tool returns up to 100 articles with specific fields and requires an API key, which are useful behavioral details beyond annotations.

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

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

The description is concise, front-loaded with the main action, then filtering options, then return details. Every sentence adds value with no redundancy.

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

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

Given 100% schema coverage and the presence of an output schema, the description is complete for this simple tool. It explains purpose, parameters, and return format adequately.

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

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

Schema coverage is 100% (baseline 3). The description adds meaningful context: lists categories, explains country code omission for global, and mentions default values (max=10, lang='en'), which go beyond the schema descriptions.

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

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

The description clearly states the tool fetches current top news headlines from GNews and lists filtering options, distinguishing it from sibling tools like search_news which likely perform specific searches.

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

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

The description mentions the requirement for an API key and optional filters, providing clear context for usage. However, it does not explicitly state when to use this tool versus alternatives like search_news, so it loses a point.

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 key behavioral details beyond annotations: ownership enforcement and that the row is deactivated (not deleted). This complements the readOnlyHint=false and destructiveHint=false annotations.

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

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

Three concise sentences with clear structure. Each sentence adds value: action, constraint, and behavior. 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?

For a simple tool with one parameter and no output schema, the description is complete. It covers ownership, deactivation vs deletion, and references related tools, providing sufficient context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds no additional meaning about the 'id' parameter beyond referencing the schema ('returned by subscribe').

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 'Cancel a subscription by id', using a specific verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions', and mentions 'recent_alerts' for historical events.

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 specifies 'Ownership is enforced — you can only cancel your own subscriptions', providing a clear condition for use. It indirectly suggests when not to use it (for others' subscriptions) but does not explicitly list alternatives beyond mentioning 'recent_alerts'.

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

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

The description adds substantial context beyond annotations: it explains internal routing, distinguishes 'could_not_verify' (check did not happen) from 'unsupported' (no source coverage), and warns against treating 'could_not_verify' as evidence. Annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false) are consistent; no contradiction.

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

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

The description is dense and packed with essential info: trigger phrases, routing, verdict taxonomy, error semantics, and replacement value. It's front-loaded with usage triggers. While longer than average, the complexity justifies the length; every sentence earns its place, though a slight restructuring into paragraphs could improve scannability.

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 the description must explain return values, and it does thoroughly: lists six verdict types, mentions 'grounded or structured actual value with pipeworx:// citation, and reasoning,' and explains error cases. It also covers the two claim categories and the fallback behavior, making it complete for a complex tool.

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

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

Input schema covers both parameters thoroughly: 'claim' includes examples, 'tolerance_pct' explains range, override behavior, and default. With 100% schema coverage, the description adds little new parameter-specific information (e.g., 'exact percent-delta math' is only indirectly related). 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 specifies verb and resource: 'validate_claim' verifies natural-language factual claims against authoritative sources. It provides trigger phrases ('fact check', 'verify the claim that...') and distinguishes itself from sibling tools by replacing 4-6 sequential calls and detailing two routing paths (SEC EDGAR+XBRL and grounded pipeline).

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: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes it replaces multi-step pipelines, making it the primary fact-checking tool. However, it doesn't explicitly name alternatives or give when-not-to-use scenarios, so it misses the full 5-point bar.

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