Press Release

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it probes multiple LLMs, requires an API key for Anthropic (passed straight through), and returns per-model objects with score, confidence, signals, and raw_response. No contradictions.

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

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

The description is concise—4 sentences, no wasted words, front-loaded with the core purpose. 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 4 parameters with full schema coverage and no output schema, the description adequately explains the return format (per-model + combined view). It also provides usage context, making it complete for an audit tool.

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

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

Schema coverage is 100% (all 4 parameters have descriptions). The description adds meaning beyond the schema: default model is Workers AI Llama-3.3-70b, the effect of `_apiKey` on Anthropic probing, and how `context` helps disambiguate. This exceeds the baseline of 3.

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

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

The description uses a specific verb ('probe') and resource ('LLMs for what they know about a business/brand/product/topic'), and clearly states the output (score 0-100 per model). It also distinguishes this tool from siblings like 'entity_profile' and 'compare_entities' by focusing on AI visibility scoring.

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 usage context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not explicitly mention when not to use it or name alternative tools for different tasks.

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=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context: the tool routes to one of 5,564 tools, fills arguments, and returns a structured answer with pipeworx:// citations. 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 verbose, spanning multiple paragraphs with some repetition (e.g., 'PREFER OVER WEB SEARCH' emphasis). It front-loads key guidance but could be trimmed without losing essential information.

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

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

Given the tool's complexity (single required parameter, no output schema), the description covers purpose, usage, examples, and return format (structured answer with citations). It lacks details on error handling but is largely complete for an agent to use effectively.

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

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

Schema coverage is 100%, so the description need not repeat parameter details. However, it adds significant semantic value by specifying the scope of permissible questions through examples and domain lists, helping the agent formulate appropriate queries.

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

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

The description clearly states the verb 'routes' with the resource 'questions', listing specific data domains like SEC filings, FDA drugs, and economic statistics. It distinguishes itself from siblings by explicitly advising to prefer over web search and 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?

Provides explicit when-to-use guidance: 'START HERE for most questions', 'Use whenever the user asks "what is", "look up"...', and 'PREFER OVER WEB SEARCH'. It also gives clear alternatives: 'Step up only when needed: for a hallucination-resistant single answer...' for ask_pipeworx_grounded, and deep_research for broad/multi-part questions.

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 cover readOnly, idempotent, destructive, openWorld. The description adds valuable context: 'Falls back to nothing — this IS a full working router, just the experimental edge' and explains that candidate improvements are enabled live when under test, with a note about the last retirement. This goes beyond annotations to clarify the beta nature and operational reliability.

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

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

The description is three sentences, front-loaded with the key purpose, then current state, then usage guidance. No filler; every sentence serves a clear purpose. Exceptionally concise for the amount of context conveyed.

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

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

Given the complexity (beta router over 5,564 tools), the description covers purpose, relationship to stable, current state, and usage. It mentions 'same response shape' but does not describe that shape; an agent unfamiliar with Pipeworx might lack detail on the output format. However, with no output schema, the description provides enough to use the tool effectively in most cases.

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

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

Schema coverage is 100% with the question parameter and its aliases fully described. The description does not add any parameter-specific meaning beyond the schema. Baseline of 3 is appropriate since schema does the full job.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, states it is 'identical universal router (same 5,564 tools, same arguments, same response shape)', and explains the experimental routing improvements. This distinguishes it from the stable sibling and conveys purpose with a specific verb ('beta version' and 'router').

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

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

The description explicitly advises to 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' It provides a clear use case (wanting the newest routing) and implies the alternative (stable ask_pipeworx). It also notes the current state (no candidate active), which helps in selection. Lacks explicit 'when not to use' but still 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?

Description adds significant behavioral detail beyond annotations: it explains the extra processing step (picking tool, fetching data, extracting answer), the exact return structure with refusal reasons, and the cost implication. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and nondestructive, so the bar is lower—description complements these well. No contradictions found.

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

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

The description is front-loaded with the core purpose and use cases, but it is slightly verbose (e.g., the list of refusal reasons and examples could be trimmed without losing clarity). Every sentence adds value, but a few could be consolidated. Still well-structured and readable.

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

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

Given the high schema coverage (100%), clear annotations, and no output schema, the description fully compensates. It explains the complete behavioral model (routing, extraction, refusal, cost tradeoff) and ties it to the tool's analog (ask_pipeworx). No gaps remain for an agent to misunderstand.

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

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

Schema description coverage is 100% (all 6 parameters are documented as aliases for 'question'), and the description clarifies that the tool accepts natural language questions. The description adds value by explaining how the question is used (routed to tools, arguments filled) but does not list all aliases; those are in the schema. A slight deduction because the description could mention that multiple aliases exist, but schema already covers this comprehensively.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' with a specific verb+resource: it picks the right tool and extracts answers using only the tool result. It distinguishes itself from siblings like ask_pipeworx (casual lookups) and lists refusal reasons, making its purpose explicit and unique.

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

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

The description explicitly says when to use ('high-stakes reads', 'answer will be quoted, cited, or acted on') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'). It provides concrete examples of appropriate use cases (financial verdicts, legal claims, medical lookups, public statements) and warns of the cost tradeoff (one extra LLM call).

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

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

The description extensively discloses behavioral traits beyond annotations, including resolution confidence levels, parent event extraction, news fallback handling, low-confidence safety checks, closed market detection, liquidity warnings, and cancellation rule parsing. All annotations (readOnly, openWorld, idempotent) are respected.

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 overly verbose, spanning multiple long paragraphs with excessive detail on edge cases and internal mechanics. While informative, it lacks conciseness and could overwhelm the agent with information density.

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 absence of output schema, the description is remarkably complete. It covers input formats, classification categories, source fan-outs, response shapes, resolution contract, safety mechanisms, edge cases (closed markets, wide spreads), and resolution-rule risk. No gaps remain.

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

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

Schema coverage is 100% and parameters are well-described in the schema. The description adds minor context (e.g., depth enumeration via quick/thorough behavior) but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states it researches a Polymarket bet, accepts multiple input types, and returns an evidence packet with comparison. It explicitly distinguishes itself from sibling tools by listing use cases like 'should I bet on X' and provides specific fan-out examples.

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

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

The description gives explicit when-to-use guidance ('Use for...') but does not explicitly state when not to use or list alternative tools. However, the context of sibling tool names and the specificity of the use cases 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?

Annotations already provide readOnlyHint, openWorldHint, idempotentHint. Description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradictions.

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

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

Front-loaded with trigger phrases and purpose. Dense with useful information but slightly long; could trim some examples. Every sentence adds value, but structure could be tighter.

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 covers return format (paired data + citation URIs), sorting, data sources, and handles edge cases like off-calendar fiscal years. Thorough for a comparison tool with two entity types.

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

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

Schema coverage is 100%. Description adds meaning by explaining what values each type expects (tickers/CIKs for company, drug names) and constraints (2–5 items). It also clarifies what data each type retrieves, going beyond the enum 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?

Description starts with trigger phrases and clearly states it performs side-by-side comparison of 2–5 companies or drugs. It differentiates from sequential single-pack lookups and lists specific data sources per entity type.

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 instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Limits to 2–5 entities and one parallel call. Could mention alternatives like entity_profile, but the guidance is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds detailed behavioral context beyond these: truthfulness policy (never invents, returns explicit gaps[]), parallel execution, depth-specific behavior (gap recovery, contradiction scanning, hop field), large-record handling (semantic excerpting), citation_uri resolvability guarantee, and expected latency (15-90s). No contradictions with annotations.

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

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

The description is comprehensive but somewhat lengthy. It front-loads the critical account requirement and fallback tool, then leads with the core capability. While every sentence adds value, the density of information could be slightly more structured (e.g., bullet points for depth differences). There is minimal redundancy, and key behavioral traits are grouped logically.

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 (2 params, rich annotations, no output schema), the description fully covers all aspects needed: prerequisites (account), input semantics (question, depth), execution model (parallel decomposition), output structure (findings packet with evidence, confidence, source, gaps, contradictions), error/edge cases (empty gaps for non-structured topics), performance expectations, and second-hop iteration logic. No output schema means the description must explain the return format, which it does thoroughly.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond the schema for both parameters: question gets natural-language decomposition context (broad/multi-part encouraged), and depth gets observable behavior per enum value (facet count, hops, contradiction scan) beyond the schema's brief enum labels. This enables informed selection of the appropriate depth.

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 1462 structured data sources, distinct from open-web search. It specifies the exact verb ('research'), resource ('Pipeworx's structured data sources'), and mechanism (decomposes into facets, routes to 5,564 tools in parallel). It also distinguishes itself from sibling tools like ask_pipeworx and ask_pipeworx_grounded by structural vs. single-lookup 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?

Provides explicit when-to-use scenarios: 'best for broad/multi-part questions over structured data' and 'compare X and Y's regulatory + financial exposure.' Clearly states when NOT to use it: 'for a single lookup use ask_pipeworx' and for 'breaking or colloquial current-news topics, prefer ask_pipeworx.' Also covers the account requirement and fallback tool (ask_pipeworx) for unsigned-in users, plus depth tier guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that the tool returns top-N results with full schemas ready to call, which goes beyond the annotations by explaining the return format and convenience.

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 for its informativeness, front-loading the core purpose. Each sentence adds value (domain list, return detail, usage advice), though it could be slightly shorter 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?

With an output schema not provided, the description still explains that results include full input schemas with examples. It covers input parameters, use case, and expected output behavior, making it sufficiently complete for the agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the main 'query' parameter's purpose and listing aliases (task, q, description, search), which helps the agent understand flexibility.

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 'Find tools by describing the data or task,' clearly specifying the verb 'Find' and resource 'tools'. It distinguishes from sibling tools by stating 'Call this FIRST' and emphasizing discovery over direct answers.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for...' and lists many domains. It also guides to 'Call this FIRST when you have many tools and want to see the option set.' While it doesn't list negative cases, the positive 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 already declare readOnlyHint, openWorldHint, idempotentHint. Description adds details on data sources, return fields (cik, filings, fundamentals, etc.), and notes about patents API sunset and soft-fail. Adds useful context without contradiction.

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

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

Description is a single dense paragraph but front-loaded with examples and every sentence adds value. Could be slightly more structured (e.g., bullet points for return fields), but overall efficient.

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

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

Given the complexity of aggregating six sources and no output schema, the description fully covers what the tool returns, including caveats like patents API sunset. Complete enough for an agent to understand behavior.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning by clarifying type is only 'company' for now, value must be ticker or zero-padded CIK, and reiterates names not supported. Provides helpful context beyond schema.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company, listing sources and examples. It implicitly distinguishes from chaining individual lookups but does not name specific sibling tools like compare_entities.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack...lookups when the user asks for a holistic view' and warns that names are not supported, directing to use resolve_entity first. Provides clear when-to-use and when-not-to-use guidance with 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 destructive and idempotent. Description adds practical context: clearing sensitive data, deleting stale memories.

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

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

Two concise sentences, front-loaded with action. 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 single-parameter tool with no output schema, description fully covers purpose, usage, and behavioral 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 covers 100% with description 'Memory key to delete'. Description adds no further parameter info beyond purpose statement.

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 'delete' with specific resource 'previously stored memory by key'. Distinguishes 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 states when to use: stale context, task done, clear sensitive data. Also pairs with remember/recall.

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

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

The description details the steps (fetch, extract, emit markdown) and is fully consistent with annotations (readOnly, idempotent, non-destructive). It adds value beyond annotations by explaining the process and output.

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, well-structured with a clear first sentence explaining the tool, followed by use cases. 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 the rich annotations and 100% schema coverage, the description fully covers the tool's behavior, output format, and intended usage. It is complete for the tool's complexity.

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

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

Schema coverage is 100%, and the description adds examples and default/max values for parameters, enhancing understanding 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 generates an llms.txt file for any URL, specifying the action and resource. It provides context about AI crawlers and the output format, effectively distinguishing it from sibling tools.

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

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

The description lists specific use cases (client indexing, own project, competitor audit), providing clear context for when to use the tool. However, it does not explicitly exclude when not to use or mention alternative tools, which would elevate the score.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds return fields but no further behavioral context beyond annotations.

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

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

Two sentences, front-loaded, 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?

Simple tool with one optional parameter; description lists all returned fields despite no output schema, making it complete.

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

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

Schema coverage is 100%, description does not add additional meaning beyond the schema's description of include_inactive.

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 statement 'List the caller's active subscriptions' with specific verb and resource. Lists returned fields. Distinct from sibling tools like subscribe/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?

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides context but could mention 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 only include four false hints, so the description carries the burden. It discloses rate limiting ('5 per identifier per day'), no quota impact, the claim_token flow for anonymous reports and follow-up, and the daily digest/roadmap impact. Some may argue this is more than needed, but it fully informs 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 information-dense with no filler. Every sentence covers a distinct aspect (scope, categories, claim_token, rate limit, cost). Front-loaded with purpose.

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

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

Given no output schema, the description explains the return via claim_token. It covers scope, prerequisites (none), rate limits, and the feedback categories. It's sufficient for an agent to decide when and how to call, and what to expect.

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

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

Schema covers 100% of the four parameters, so baseline is 3. The description adds meaningful usage semantics: explains claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and advises against pasting end-user prompts for the message field. This pushes it 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 opens with a clear action ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates feedback categories (bug, feature/data_gap, praise). It distinguishes from sibling tools (research, ask, etc.) by focusing on feedback about the Pipeworx connection itself.

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

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

Explicitly specifies when to use: for bugs, feature/data_gap, praise. Provides a clear exclusion: tools from other MCP servers are out of scope, with guidance to file with that server. Also clarifies how to identify Pipeworx tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context: data sourcing from CF analytics-engine, no PII, caching behavior (5min-1h), which enriches the agent's understanding 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 well-structured sentences and a bulleted list of use cases. Every sentence adds value, and the key information (what it does, use cases, how it works) is front-loaded 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?

For a simple tool with one optional parameter and no output schema, the description covers the essential aspects: what is returned (top tools, top packs, total call volume), use cases, and data source. It lacks explicit output structure details, but given the tool's simplicity, it is nearly complete.

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

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

The schema description coverage is 100%, with the parameter 'window' fully described (enum values, default, usage guidance). The main description does not add new parameter semantics beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window, with a specific verb and resource. It distinguishes from sibling tools by focusing on trending data, a unique 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 explicitly lists three use cases (discovering hot data sources, confirming canonical choices, aligning use case with trends), providing clear when-to-use guidance. However, it lacks explicit when-not-to-use or alternative tools, preventing a top score.

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

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

Annotations already declare readOnly and idempotent, so the tool is safe. The description adds extensive behavioral context: monotonicity checks, partition sum logic, semantic anchor constraints (≥0.30 Jaccard similarity), partition filter for placeholder slugs, fill check with CLOB depth and realizable edge. It also explains the response structure and trade signals.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Front-loaded with main purpose and modes. Every sentence is informative, though slightly verbose in some technical explanations.

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 is provided, but the description fully compensates by detailing the response structure (opportunities array with fields, partition_check details). It covers all modes, constraints, and edge cases, making the tool self-explanatory despite the lack of an output schema.

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

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

Input schema covers both optional parameters with descriptions. The description adds significant value: explains how event slugs work, that full URLs are accepted, what topic expects (seed question), and the behavioral differences between modes. Schema coverage is 100%, but the description provides crucial 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?

Clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Distinguishes three modes: no args (trending scan), event (specific market), topic (cross-event). This differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly tells when to use each mode: no args for trending, event recommended for specific market, topic for cross-event scanning. Provides guidance on when not to trade (fill check shows realizable_edge_pp ≤ 0) and directs to another tool 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, openWorldHint, idempotentHint, destructiveHint. The description adds significant value: caching details (1h KV-level keyed on knobs), diagnostic output for empty segments, Fed bets exclusion rationale, and detailed model family breakdown. 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 extremely long and technical, including detailed model family explanations that could be external. It front-loads purpose but quickly becomes verbose, risking overwhelm for an AI agent seeking efficient parsing.

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

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

Given the tool's complexity (9 params, no output schema), the description is remarkably complete. It explains output structure (by_segment, diagnostics), caching, knob interactions, and edge cases like Fed bets. No gaps.

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

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

Schema description coverage is 100% with rich descriptions. The tool description adds nuance, e.g., explaining why min_kelly doesn't filter partition arbs and how min_partition_leg_kelly applies instead. This goes beyond the schema, justifying a 4.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also positions it for 'what should I bet on today' discovery, distinguishing it from siblings like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description implicitly guides usage by explaining the tool is for discovering Pipeworx-vs-market disagreements without paging. However, it lacks explicit when-to-use vs alternatives or when-not-to-use guidance, which would improve clarity.

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 snapshot generation conditions, decay computation method, slippage assumptions, and response structure with details like 'first_seen', 'trend', 'decay_pp_per_day', and 'lifespan_days', which add significant value beyond annotations.

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

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

Well-structured with purpose first, then args, then response breakdown. Slightly verbose but every sentence adds value. Could trim 'the latter is wide...' without losing clarity but it's acceptable.

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 response fields (tracked, expired, snapshot_dates) and behaviors. With annotations covering safety, it's complete for agent usage.

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

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

Schema coverage is 100%, and description adds meaning: explains default and range for 'days', clarifies 'window' as snapshot family with examples. Baseline 3 increased due to added value.

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

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

Description clearly states verb (track/analyze) and resource (edge persistence/decay), differentiates from sibling polymarket_edges by focusing on historical trends and decay, not just current edges.

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

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

Provides context on when to use (comparing fresh vs old edges) and limits (60-day TTL, snapshot start). Does not explicitly list exclusions or alternative tools, 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?

The description details the tool's behavior: it walks the order book ladder, returns top_of_book, VWAP fill price, slippage, fill details, and a verdict. It warns about partial basket fills converting an arb into a directional position. Annotations (readOnlyHint, idempotentHint, destructiveHint false) align with this being a read-only check.

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

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

The description is well-structured with clear sections for single-market and basket modes, and front-loaded with the core purpose. It is somewhat lengthy but every sentence adds value given the tool's complexity. A slight reduction in verbosity could improve conciseness.

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

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

Despite no output schema, the description thoroughly covers return fields (top_of_book, VWAP, slippage, verdict, etc.) and explains the logic for both modes. It also addresses edge cases like thin legs and directional risk.

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 beyond the schema. For example, it explains the default side auto-detection for baskets, and how size_usd is interpreted differently for single-market vs basket (spend vs settlement notional).

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 a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by being a pre-execution check.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains when to use single-market vs basket mode and warns about partial basket fills.

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

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

Goes far beyond annotations by detailing safety fields (compatibility_warning, temporal_alignment, skipped counters) and explaining conditions under which spreads are invalid. Annotations already indicate safe read-only operation, and the description provides rich behavioral context.

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

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

The description is lengthy but dense with necessary information. It is front-loaded with purpose, then logically flows through modes, response, and safety fields. A minor reduction in verbosity could improve conciseness, but every sentence serves a purpose.

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

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

Given the tool's complexity, the description covers input modes, output details, edge cases (compatibility warnings, temporal alignment), and limitations. It leaves no important aspect unexplained, making it fully sufficient 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?

All three parameters have full schema coverage and the description adds extra context: topic shortcuts, explicit override behavior, and how parameters affect responses. It also explains the output structure, compensating for the lack of an output 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing specifically on inter-venue spreads.

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

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

Explicitly describes two modes (topic and explicit), provides examples, and warns that pre-mapped topics often return compatibility warnings. It explains when spreads are meaningful and when they are not, giving clear usage boundaries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds value by detailing the output structure (headline, body, boilerplate, media contact), which helps the agent understand what to expect from invocation.

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

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

The description is a single, dense sentence that presents the main purpose first and includes all necessary details with no wasted words.

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

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

Given the presence of an output schema (not shown but mentioned), the description's mention of the return structure is supplementary. All parameters are covered, and the annotations provide safety cues, making the description fully adequate for an agent to use the tool correctly.

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

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

Schema description coverage is 0%, but the description explicitly lists all four parameters (announcement, optional company, location, tone) and explains their roles. It also enumerates the allowed tone values, compensating for the missing 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 uses a specific verb-resource pair ('Transform any announcement into a satirical press release') and clearly distinguishes this tool from siblings, as none of the other tools produce press releases or satire.

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 implies usage context (for turning announcements into satirical releases) but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: scoped to identifier (anonymous IP, BYO key hash, account ID) and the ability to list all keys by omitting the argument. No contradictions.

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

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

The description is concise and well-structured: first sentence defines core function, second gives use cases, third explains scoping, fourth pairs with siblings. Every sentence adds value without redundancy.

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

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

Given no output schema, the description adequately explains what the tool returns (a value or list of keys). It covers idempotency implicitly. While return format is not detailed, it is sufficient for an agent to understand the outcome.

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 clear description for the 'key' parameter. The description adds value by explaining the dual behavior (retrieve vs. list) and providing usage examples. This goes beyond the schema alone.

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

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

The description clearly states the verb ('retrieve' or 'list') and the resource (previously saved memories via 'remember'). It distinguishes from siblings by explicitly pairing with '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 provides clear context for use: looking up stored context like target ticker, address, or research notes without re-deriving. It also explains scoping by identifier. While it doesn't explicitly state when not to use or name alternatives, the guidance is sufficient for appropriate usage.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds that setting mark_read:true flags events as read, affecting subsequent calls, which is a behavioral nuance beyond annotations. It also notes that polling works fine, implying no side effects.

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 at 4 sentences, front-loading the core purpose. Every sentence adds value: purpose, key fields, filtering options, behavioral note, and alternative access method. 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?

Although there is no output schema, the description explicitly lists the fields returned (source, citation_uri, raw event payload). It covers input parameters, behavioral options, and even mentions alternative access for scripting, making it fully self-contained.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description enriches these by providing examples (e.g., 'sec_8k' for type, ISO timestamp for since) and explaining the side effect of mark_read:true. This adds practical meaning beyond the schema alone.

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

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

The description opens with 'Pull fired events from your subscription feed,' clearly specifying the verb and resource. It distinguishes the tool by focusing on subscription feed events, unlike sibling tools like list_subscriptions or recent_changes.

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 filtering by type and ISO timestamp, and the mark_read option for stateful polling. It also mentions that the same feed is available at an alternative endpoint for scripts/dashboards, providing context for when to use this tool vs. direct API access. However, it does not explicitly contrast with sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint; the description adds details about fanning out to multiple sources, fallback behavior, and output structure. No contradictions.

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

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

The description is well-structured, front-loading purpose and examples, then detailing sources, parameters, and return value. It is relatively long but every sentence adds value; minor redundancy in example queries.

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

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

Given no output schema, the description explains the return structure (changes[] grouped, total_changes, URIs). It covers limitations (USPTO soft-fail) and fallback logic, though error handling is not fully detailed.

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%; the description adds examples for the 'since' parameter (e.g., '7d', '30d') and clarifies the 'value' parameter accepts ticker or CIK, but does not significantly extend beyond the schema.

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

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

The description clearly states the tool provides a change feed for a company in a time window, using example queries to illustrate use cases. It distinguishes itself from sibling entity_profile by noting when to use the alternative.

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

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

The description gives explicit guidance on when to use entity_profile instead, and explains the fallback mechanism for GDELT→GNews. It does not cover all sibling tools but provides good context for the primary alternative.

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

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

Annotations indicate idempotent and non-destructive. Description adds context about session-based persistence: 'authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'. 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 four sentences, each well-formed and informative. It front-loads the purpose, then provides usage context and storage details without 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 key-value store with complete parameter schema, the description covers essential aspects: what to store, scope, duration, and links to related tools. Could mention overwrite behavior for existing keys, but not critical.

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

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

Schema coverage is 100% with descriptions for both parameters. The tool description adds value by providing concrete examples of key names and value types, aiding the agent in proper usage.

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

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

The description clearly states the verb 'save data' and the resource 'data the agent will need to reuse later'. It includes specific examples like 'resolved ticker', 'target address', 'user preference', and distinguishes from siblings 'recall' 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?

Explicitly says when to use: 'when you discover something worth carrying forward'. It also mentions complementary tools: 'pair with recall to retrieve later, forget to delete', providing clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and side-effect behavior. The description adds valuable behavioral context: graceful degradation ('LEI/FIGI enrichment degrades gracefully — if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), internal cascading ('Each call cascades through several lookup endpoints internally'), and output details ('every identifier is labelled with the source that established it, and an identifier that could NOT be resolved is stated explicitly under unresolved'). These details enhance transparency beyond annotations.

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

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

The description is relatively long and dense with details, which supports completeness but sacrifices conciseness. It is front-loaded with examples and the usage directive, but the paragraphs about supported types and graceful degradation are verbose. Every sentence provides useful information, but there is room for tighter phrasing without losing content. For example, the technical details about LEI/FIGI could be condensed.

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

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

Given the tool's complexity (multiple data sources, cascading lookups, no output schema), the description covers the key aspects: core function, input formats, output behavior (identifiers labeled with source, unresolved listed), fallback behavior, and a note that it replaces multiple manual steps. It informs the agent about what to expect without specifying exact JSON structure, which is acceptable as no output schema exists. The only minor gap is that the exact output format (e.g., whether results are returned as a flat object or nested) is implied but not explicitly structured.

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 significant meaning: for the 'type' parameter, it elaborates on the company type with a detailed explanation of what identifiers are returned (CIK, ticker, LEI, FIGI) and their sources (SEC EDGAR, GLEIF, OpenFIGI), and for drug type, it specifies RxCUI, ingredient, brand, and a citation link. For the 'value' parameter, it gives multiple input formats for company (ticker, CIK, ISIN, name) and notes that ISIN resolves via GLEIF ISIN-to-LEI mapping for non-US issuers. This goes well 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 opens with multiple concrete examples of user queries ('What's the ticker for…', 'find the CIK for…') and then states the core function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' This clearly identifies the verb (resolve) and resource (name to identifiers), with explicit scope (supported types company and drug). It distinguishes itself from siblings via the directive 'Use FIRST whenever you have a name but need an ID.'

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

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

The description explicitly tells the agent when to use this tool ('Use FIRST whenever you have a name but need an ID'), which provides clear context for selection. It does not list specific sibling alternatives or exclusions, but the directive strongly implies that for name-to-ID tasks, this is the primary choice. The mention that it 'replaces 2-3 manual lookups' further reinforces its role.

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 false, so the safety profile is clear. The description adds value by revealing internal behavior: it probes each entity using 'ai_visibility_check', then ranks results. 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 only 3 sentences, front-loaded with the purpose. Every sentence provides essential information: what it does, how it works, and when to use it. No redundant or vague statements.

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 explicitly states the return format ('ranked list with score, confidence, signal density per entity'). Parameters are fully covered by schema. Annotations handle behavioral aspects. The description is complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds helpful context: it notes that the first entity is treated as the 'subject' for narrative and explains the role of 'entities' as 'your brand + N competitors'. This goes beyond the schema's literal 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 'Compare AI visibility across multiple entities side-by-side', specifying a concrete verb and resource. It distinguishes itself from the sibling tool 'ai_visibility_check' (single entity) and 'compare_entities' (generic comparison) by focusing on AI visibility ranking.

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

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

The description provides a clear use case ('competitive AI-marketing audits') with an example question. While it doesn't explicitly list when not to use it or name alternatives, the context is strong enough for the agent to understand when this tool is 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?

Annotations already indicate readOnly, openWorld, idempotent, not destructive. The description adds details about fan-out to deps.dev and bundlephobia, partial failure handling, and 5-30s delay for first bundlephobia measurement, which are not in annotations.

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

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

The description is a single paragraph that efficiently packs all key information. It is front-loaded with purpose, then details. Somewhat dense but retains readability.

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

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

Despite no output schema, the description explicitly lists all return fields (summary block, per-advisory, links, alternatives) and covers edge cases (partial failures, version default). Complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds useful context: acceptance of scoped packages and default version behavior, which goes slightly beyond schema descriptions.

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

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

The description clearly states it's a composite check for npm packages covering license, advisories, bundle size, etc. It distinguishes itself from sibling tools by specifying NPM-only and referencing deps.dev:version for other ecosystems.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and notes NPM-only scope, with alternative 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?

Adds significant behavioral details beyond annotations: mentions BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flagging, and output includes offsets and scores. No contradiction with readOnly/idempotent hints.

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

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

Compact and front-loaded: first sentence states core function, followed by usage guidance, pairing hint, and technical details. Every sentence serves a purpose 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 no output schema, description fully explains input requirements, behavior (embedding model, windowing, truncation), and output format (passages with offsets and scores). Also covers pairing with sibling 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 already has 100% coverage with descriptions. Description adds context by explaining text is a pre-fetched document, query is natural language, and limit controls top-N passages. Overarching context is provided but per-parameter elaboration is minimal.

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

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

Description clearly states the tool performs semantic search inside a fetched record, with specific verbs ('Search Within a Source') and examples (SEC 10-K, article). It distinguishes from sibling ask_pipeworx_grounded by explaining the pairing.

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

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

Provides explicit guidance: use when record is too large for prompts, pairs with ask_pipeworx_grounded for grounding. Lacks explicit exclusion for small records, but context clearly implies the appropriate scenario.

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

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

Annotations indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds critical behavioral context: returns new subscription id (non-read-only), requires OAuth account, and details delivery constraints (phone verification, SMS cap, webhook auto-disable). 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 dense but well-structured, front-loading the main purpose. It uses periods to separate sections, making it scannable. However, it is somewhat lengthy and could benefit from more explicit bullet points or sections for readability 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?

The tool is complex (multiple types, delivery channels, constraints) and has no output schema. The description covers all essential aspects: return value (subscription id), all subscription types with param examples, delivery channels with constraints, and OAuth requirement. No gaps identified.

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 value beyond the schema: examples for each subscription type's params (e.g., sec_8k items, polymarket_edge topic), and detailed explanations for delivery channels (phone verification, 10/day cap, webhook HMAC signing). This compensates fully for any lack of schema detail.

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 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb (Create) and resource (subscription). It distinguishes from sibling tools like list_subscriptions (list), unsubscribe (remove), and recent_alerts (pull alerts) by focusing on creation.

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

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

The description provides explicit when-to-use scenarios and requirements (Pipeworx OAuth account, anonymous/BYO limitation). It details supported subscription types and delivery channels. However, it does not explicitly say when not to use (e.g., use list_subscriptions to check existing subscriptions first), though context implies alternatives.

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

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

The description adds context beyond annotations: it reveals the tool draws from a 'live catalog of thousands of tools' and returns exact tool+argument shapes. Annotations already mark it as read-only, idempotent, and non-destructive, so there is no contradiction.

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

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

The description is somewhat lengthy but well-structured with example queries at the start. Every sentence contributes useful information, though it could be slightly more compact 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?

The description covers all necessary aspects: purpose, usage, return type (category-bucketed example questions with tool+argument shapes), and optional filtering. Since there is no output schema, the description adequately explains what to expect, making the tool complete for an agent.

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

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

Schema coverage is 100% for the single parameter 'topic'. The description enriches it by listing example focus areas (finance, pharma, etc.) and explaining that omitting it returns a full cross-category spread, adding practical value beyond the schema's description.

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

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

The description clearly identifies the tool as the onboarding entry point, listing example user intents like 'what can I ask?' and 'getting started'. It specifies it returns category-bucketed example questions with tool+argument shapes, distinguishing it from other tools by being the first point of call.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also explains the optional topic parameter to focus on specific areas, providing clear guidance on when 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 indicate idempotentHint=true and destructiveHint=false. The description adds that the row is deactivated (not deleted) and historical events stay, consistent with non-destructive behavior. It also mentions ownership enforcement, which is not in annotations. No contradiction.

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

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

Two concise sentences. First sentence gives the purpose. Second sentence adds key behavioral details. No wasted words, front-loaded.

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

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

Describes input (id), behavior (ownership, soft delete), and side effects (historical events preserved). No output schema exists, so return value not required. Slight gap: no mention of success/error response, but overall adequate for a cancellation tool.

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

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

Schema coverage is 100% with one parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' The description adds 'by id' but no additional meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description states 'Cancel a subscription by id.' The verb 'Cancel' and resource 'subscription by id' are specific. It clearly distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

It states 'Ownership is enforced — you can only cancel your own subscriptions.' This provides context on when to use (own subscriptions) and implicitly when not (others'). It also explains the deactivation behavior. However, no explicit alternatives or when-not scenarios beyond ownership.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive, but the description adds substantial behavioral context: it explains the two routing paths (SEC EDGAR vs. grounded), the verdict set, and the crucial distinction between could_not_verify (verification failure) and unsupported (no source coverage). This goes well beyond the annotations and provides operational nuance.

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 every section earns its place: trigger phrases, purpose, routing detail, return values, and caller caveats. It is front-loaded with usage triggers and ends with critical guidance. Though verbose, it avoids fluff and is well-organized for a tool with this 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 having no output schema, the description fully documents return values (verdict, actual value with citation, reasoning) and error semantics (verification_error in could_not_verify, meaning of unsupported). With only 2 parameters and a clear description, it is complete for an AI 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%, but the description adds meaning beyond the schema. It specifies that tolerance_pct overrides the implied tolerance from claim wording, recommends 1–2 for hallucination detection, and clarifies the default cap is 5. It also gives examples for the claim parameter, making both parameters more actionable.

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: natural-language claim verification against authoritative sources, with explicit trigger phrases like 'fact check' and 'verify the claim that…'. It distinguishes itself by specifically mentioning the SEC EDGAR fast path for company-financial claims and the grounded pipeline for other claims, which differentiates it from siblings like ask_pipeworx_grounded.

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 says 'Use whenever the agent needs to check whether something a user said is factually correct.' It details when the structured SEC EDGAR path applies vs. the grounded pipeline, and highlights important call-handling semantics (could_not_verify vs. unsupported) that instruct when not to treat a result as evidence. Also notes it consolidates 4–6 sequential calls, implying it's the preferred tool for this workflow.

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