Emoji

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: return format (score, confidence, signals, raw_response), default model (free), and the fact that Anthropic calls require a BYO key with direct payment. No contradictions.

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

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

The description is a single, well-structured paragraph. It front-loads the primary action and return format, appends usage scenarios, and avoids fluff. 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 no output schema, the description details the return structure. It covers all parameters, provides usage context, and explains the optional key for Anthropic. No gaps for this 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 extra meaning beyond schema by clarifying the default model, explaining that _apiKey is for Anthropic and requires BYO key, and that context helps disambiguate. This added context justifies a 4.

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

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

The description clearly states the tool probes LLMs for business/brand/product/topic visibility and scores it 0-100 per model, with a specific verb and resource. It differentiates from siblings like scan_competitor_ai_presence by focusing on LLM knowledge rather than search or edge detection.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and clarifies when to supply an API key for Anthropic. However, it does not explicitly state when not to use this tool or name alternatives, so it falls short of a 5.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds valuable context beyond this: it routes to one of 5,305 tools, fills arguments, and returns answers with stable pipeworx:// citation URIs. It also notes it works on every tier and is 'one fast call', though it does not mention potential failure modes or rate limits, so it stops short of full transparency.

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

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

The description is long but every sentence earns its place: it opens with a clear directive ('PREFER OVER WEB SEARCH'), specifies supported domains, states the default-entry-point role, lists alternatives with conditions, and gives concrete examples. It is front-loaded and efficiently structured for an AI agent.

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 complex tool that routes across many sources, the description provides comprehensive context: what it does, when to use it, how it differs from alternatives, and what output to expect (structured answer with citations). No output schema exists, so the description appropriately covers return value expectations.

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

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

Schema coverage is 100%, so the schema fully documents all parameters. The description's examples ('What was Apple's revenue in 2024?', 'Any recent SEC filings for $NVDA?') provide practical usage context, but it does not need to compensate for schema gaps. This meets the baseline for well-documented parameters.

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

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

The description clearly identifies the tool as a natural language question answerer that routes to thousands of sources and returns structured answers with citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its unique scope evident.

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 is explicit about when to use this tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when to use alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). It even provides example queries to illustrate appropriate use.

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

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

The description discloses that it is experimental, may have routing improvements enabled, and that it currently matches ask_pipeworx exactly since no candidate is active. It explains the 'beta' behavior beyond annotations by noting it is a working router and results are compared to the stable version. This adds context beyond the read-only and idempotent hints, though it could detail potential instabilities or differences in edge cases.

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 few sentences long and front-loaded with the key fact that it is a beta version. Each sentence adds meaningful context (identical router, current status, usage guidance, and fallback clarification), making it efficient without being overly verbose.

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

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

Given the complexity of a universal router with 5,305 tools, the description thoroughly explains what the tool does, how it relates to the stable version, when to use it, its current behavior, and that it is fully functional. It also addresses the response shape, making it complete 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?

All six parameters are fully described in the schema with 100% coverage, and the description does not add specific parameter semantics beyond stating it uses the same arguments as ask_pipeworx. With complete schema coverage, the 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 is a beta version of ask_pipeworx, an identical universal router with the same 5,305 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by specifying it may have candidate routing improvements, making the purpose specific and differentiating from siblings.

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

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

The description explicitly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing' and contrasts it with the stable router for comparison. It also clarifies that it is a full working router, not a fallback, providing clear when-to-use guidance and an implied alternative.

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

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

The description discloses return behavior (evidence as verbatim quote, confidence, source, fetched_at) and explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). Annotations already mark it read-only/idempotent; the description adds refusal behavior, grounding approach, and extra LLM cost 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 lengthy but front-loaded with the core purpose ('Hallucination-resistant answer mode'). Every sentence serves a purpose: mode, process, return/refusal structure, usage, and cost. Slightly dense but not wasteful; justified by the tool's complexity.

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

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

Covers purpose, routing scale (5,305 tools across 1391 sources), return type, refusal reasons, when to use, and cost comparison. Since there is no output schema, the return structure details are necessary. The tool is complex and the description provides enough for an agent to select and invoke it accurately.

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 6 parameters are aliases for 'question' and the schema documents them fully with 'Your question in natural language'. The tool description does not add parameter-specific semantics beyond the schema; with 100% schema description coverage, the baseline 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 it is a 'Hallucination-resistant answer mode for high-stakes reads' and explains the process of routing to tools and extracting answers only from tool results. It distinguishes itself from siblings like ask_pipeworx by emphasizing the grounded extraction and explicit refusal behavior.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on' and contrasts with 'prefer ask_pipeworx for casual lookups.' It names the alternative and the cost trade-off (one extra LLM call), providing clear when-to-use and when-not-to-use guidance.

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

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

The description extensively discloses behavioral traits beyond the annotations: it explains how the tool resolves markets, classifies bets, fans out to data sources, handles low-confidence matches (short-circuiting), closed markets, wide spreads, and cancellation rules. It warns about market_match_confidence and recommends inspection before trusting analysis. This far exceeds what annotations provide.

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

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

The description is lengthy but well-structured using sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) which aids readability. It is front-loaded with the core purpose and then details edge cases. While every sentence adds value, the length could be reduced 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 and absence of an output schema, the description comprehensively covers input variants, response shapes, safety mechanisms, error states, and even cancellation rule parsing. All edge cases are addressed, making the tool fully understandable without additional documentation.

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

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

With 100% schema coverage, the description adds significant value: it explains the difference between 'quick' and 'thorough' depth (2-3 sources vs full fan-out), defaults, and when to use include_raw (summarized vs full payloads). Examples for the 'market' parameter clarify input formats (slug, URL, question text). No gaps remain.

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: researching a Polymarket bet by pulling relevant Pipeworx data. It provides specific verb-resource combinations ('Research a Polymarket bet', 'pulling the relevant Pipeworx data') and distinguishes itself from sibling tools like polymarket_edges by focusing on single-bet deep research. Examples of inputs and outputs further clarify its function.

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

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

The description gives explicit usage scenarios ('should I bet on X', 'what does the data say about Y') and provides detailed fan-out examples for different bet categories. While it does not explicitly state when not to use the tool versus alternatives, the context from sibling tool names implies differentiation. The guidance is clear and actionable.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds substantial context: for companies pulls 10-K data with fiscal year handling, for drugs pulls FAERS/FDA/trial counts, results sorted, returns 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?

Description is front-loaded with example queries, every sentence adds value, no fluff. Efficiently conveys complex behavior in concise paragraphs.

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?

Comprehensive coverage: includes entity types, data sources, sorting, output format (paired data + citations), and edge case (off-calendar fiscal years). No output schema but description explains returns adequately.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds value by explaining 'values' format (tickers/CIKs for company, names for drug) and what data each type pulls, going 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 does side-by-side comparison of 2-5 companies or drugs, with specific example queries. It distinguishes from sibling tools like entity_profile by noting it replaces sequential lookups.

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

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

Explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Also implies alternatives (entity_profile for single entities) through 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?

Goes far beyond annotations: requires account/payment, clarifies the tool is not open-web search, details the findings packet format (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), explicitly states gaps[] are never invented, explains semantic excerpting, and gives latency expectations (15-60s, up to ~90s). Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent with this description; 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 long, but this is a complex tool with many caveats. It is front-loaded with the most critical constraint (ACCOUNT REQUIRED) and then flows through the mechanism, use cases, alternatives, limitations, and latency. A few sentences could be trimmed, but every part contributes meaningful guidance.

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

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

There is no output schema, so the description carries the burden of explaining return values — it does so thoroughly: 'findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[]'. It also covers second-hop behavior, contradictions[], and latency, making it complete for a research tool of this complexity.

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

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

Schema coverage is 100% with solid parameter descriptions, so baseline is 3. The tool description adds extra value by explaining depth behavior ('quick=3... standard=5... thorough=8 (paid)') and clarifying that 'question' may be broad/multi-part, enriching the understanding of both parameters.

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

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

The description opens with a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1391 STRUCTURED data sources' and explains the mechanism ('Decomposes your question into focused facets, routes each to the right one of 5,305 tools IN PARALLEL'). It clearly distinguishes itself from open-web search and from siblings like ask_pipeworx and bet_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 and when-not-to-use guidance. It states 'Best for broad/multi-part questions over structured data', instructs 'For a single lookup use ask_pipeworx', warns 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and even handles the not-signed-in case: 'If you are not signed in, use ask_pipeworx instead'.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral detail: returns 'top-N most relevant tools' with schemas and curated examples, and that results are 'ready to call directly, no second schema lookup needed'. No contradiction.

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

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

The description is concise (3 sentences) yet packs purpose, usage, examples, output details, and workflow guidance. Front-loaded with the main verb and resource. Every sentence adds essential information without redundancy.

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

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

No output schema exists, but the description fully explains what is returned: top-N tools with names, descriptions, full input schemas, and curated examples. Covers the tool's role as a discovery gateway, parameter usage, and readiness for direct invocation.

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

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

Schema has 6 parameters with 100% description coverage. The description goes beyond by explaining that query accepts natural language like 'analyze housing market trends' and lists aliases (task, q, description, search). Adds value to what the schema provides.

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

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

The description uses specific verbs like 'find', 'browse', 'search', and 'discover' to state the tool's function, and lists diverse domains (SEC filings, FDA drugs, etc.) to clarify scope. It distinguishes itself from sibling tools by recommending calling this first when many tools are available.

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: 'Use when you need to browse, search, look up, or discover what tools exist for...' and provides concrete examples. Also advises 'Call this FIRST when you have many tools available', providing clear guidance on placement in workflow.

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

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

Annotations already indicate readOnly, idempotent, openWorld, and non-destructive behavior. The description adds valuable context: 'Keyless, offline,' and specifies the return format (character + keywords or shortcode/name). This goes beyond the annotations and fully discloses the tool's behavior in a transparent manner.

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

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

The description is extremely concise: two short sentences that front-load the key information. Every word serves a purpose, with no filler or redundancy.

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

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

Given the tool's simplicity (one parameter, no output schema, annotations covering safety), the description covers all necessary information: input formats, return types, keyless and offline nature. No gaps are present.

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

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

The input schema has 100% coverage for the single parameter 'input', with a description that matches the tool's text. The description adds examples but does not provide significant new meaning beyond the schema. Baseline 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's purpose: 'Look up an emoji by :shortcode:' or by passing an emoji character to get its name. It specifies two distinct modes of operation, making it easy to understand what the tool does. The sibling list includes 'search_emoji', which suggests a different functionality (search vs. exact lookup), providing implicit distinction.

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 on when to use the tool: for shortcode-to-emoji or emoji-to-shortcode lookups. However, it does not explicitly state when not to use it or mention alternatives like 'search_emoji'. The guidance is implied but not exhaustive.

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, destructiveHint=false. The description adds significant detail: it fans out across multiple sources, lists exact return fields (cik, filings with URIs, fundamentals, patents with sunset note, news fallback, LEI). 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 front-loaded with the core purpose and example queries, then details return types. While it is relatively long, every sentence adds value. Minor redundancy in repeating the 'names not supported' point could be trimmed, but overall structure is good.

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 2 parameters, 100% schema coverage, and no output schema, the description provides a thorough explanation of the return data (CIK, filings, fundamentals, patents with caveat, news fallback, LEI) and usage context. It is complete for the intended use case.

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 substantial value beyond the schema. For the 'type' parameter it clarifies only 'company' is supported and hints at future types. For 'value' it gives concrete examples (ticker or CIK), explicitly states names are not supported, and directs to resolve_entity as alternative.

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 example queries and clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call.' The purpose is specific and resource-identified, but it does not fully distinguish from all sibling tools like deep_research or compare_entities, though it does contrast with chaining single sources.

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

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

Explicitly states when to use: when a user asks for a holistic view (e.g., 'Tell me about X'), and advises against chaining multiple lookups. Also provides clear guidance on what inputs are not supported ('names not supported — use resolve_entity first') and notes a partial failure mode for patents.

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

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

Annotations already declare 'destructiveHint: true' and 'idempotentHint: true', so description doesn't need to repeat destruction. It adds context for when to use, but no additional behavioral traits beyond annotations.

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

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

Two sentences with zero waste. Every sentence adds value: purpose, usage guidelines, and relation to sibling tools.

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

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

For a simple single-parameter tool with sufficient annotations and no output schema, the description covers purpose, usage, and tool relationships completely.

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

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

Schema coverage is 100% and parameter description 'Memory key to delete' is clear. The tool description adds no extra meaning beyond what the schema already provides, meeting the baseline.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying both the action and resource. It distinguishes from sibling tools like 'remember' and 'recall' by explicitly pairing with them.

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

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

Provides clear use cases: 'when context is stale, the task is done, or you want to clear sensitive data'. It implicitly suggests alternatives by noting to pair with 'remember' and 'recall', but lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds that it fetches and extracts data, but this is implicit from the read-only nature. Only marginal additional 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 with a list of use cases. Every sentence adds value: what it does, how it works, output format, and when to use. 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?

For a simple tool with full schema coverage and rich annotations, the description explains output format and use cases well. Missing error conditions, but not critical for this tool.

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

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

Schema coverage is 100%, so the description adds no new meaning beyond what the schema already provides for 'url' and 'max_links'. Baseline 3 is appropriate.

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

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

Clearly states it generates an llms.txt file for a URL, with specific verb (generate) and resource (llms.txt). Distinct from all sibling tools, which are about research, visibility, and other tasks.

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

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

Explicitly lists three use cases: indexing client sites, drafting for own project, auditing competitors. Does not mention when not to use or alternatives, but the specialized nature makes usage 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, idempotentHint, destructiveHint. Description adds return field details and optional parameter behavior, complementing annotations without contradiction.

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

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

Two concise sentences: first states purpose and return fields, second gives usage guidance. No unnecessary words.

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

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

Given the simple one-parameter tool with rich annotations, the description fully covers purpose, return structure, and usage context.

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

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

Schema coverage is 100%; description does not add additional meaning to the include_inactive parameter beyond what schema provides. Baseline score of 3.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes from siblings like subscribe and unsubscribe.

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

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

Explicitly states when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Does not explicitly mention alternatives but provides 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 are present but the description adds important behavioral details: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota. No contradiction with annotations.

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

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

The description is a single well-structured paragraph that front-loads the purpose, then provides usage guidance, and ends with behavioral notes. No redundant sentences.

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 3 parameters (one nested object) and no output schema, the description is fully complete: it explains input, usage, behavioral constraints, and what the tool achieves. 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 has 100% description coverage, but the description adds extra context: explains each enum value type, recommends 1-2 sentences and 2000 chars max for message, and advises describing issues in terms of Pipeworx tools/packs.

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 sends feedback to Pipeworx about bugs, missing features, data gaps, or praise. It uses specific verbs (tell, describe) and distinguishes from sibling tools which are unrelated to feedback.

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

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

Explicitly lists when to use (bug, feature/data_gap, praise) and what not to do (don't paste end-user's prompt). Also mentions rate limits and that it's free. Provides clear context for usage vs 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. The description adds value by specifying the data source (CF analytics-engine), privacy (no PII), and caching (5min-1h). This provides 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?

The description is three concise sentences, front-loaded with the core functionality and use cases. Every sentence contributes value, and there is no redundancy or filler.

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 low complexity (single optional parameter, no output schema), the description covers purpose, use cases, data source, caching, and parameter guidance. It lacks explicit return type definition but describes the output as 'top tools, top packs, and total call volume,' which is sufficient.

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

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

Schema coverage is 100% with one optional enum parameter. The description adds meaning by explaining the trade-offs between window lengths ('shorter windows surface what's hot right now; longer windows show steady-state demand'), which goes beyond the schema's enum values.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over recent time windows, with a specific verb ('returns') and resource ('what other AI agents are calling on Pipeworx'). This distinguishes it from sibling tools like 'ask_pipeworx' or 'discover_tools' by focusing on aggregated trending data.

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

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

The description lists three explicit use cases (discovering hot data sources, confirming canonical choices, aligning use cases) and notes caching behavior. It does not explicitly state when to avoid using the tool, but the use cases provide clear context 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 indicate read-only, idempotent, non-destructive. Description adds details about Jaccard similarity, partition filter, fill check against CLOB depth. 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?

Well-structured with clear sections and examples, but slightly verbose for the complexity. Each sentence adds value, but could be tightened.

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?

Explains output (opportunities array, partition check, fill check) adequately despite no output schema. Missing details on error handling or edge cases, but sufficient for an AI agent.

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

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

Schema coverage is 100%. Description adds examples and explains the distinction between event and topic modes 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 what the tool does: find arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific purposes.

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

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

Provides explicit when-to-use guidance for each parameter (no args for trending scan, event recommended for specific market, topic for cross-event). Mentions alternatives like polymarket_fill_risk for custom sizing and warns when not to trade.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are all consistent with the description. The description adds rich behavioral context including caching at the KV level, model family details, edge calculation, and diagnostic output, far exceeding what annotations alone provide.

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

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

The description is very dense and includes extensive technical details (e.g., exact alpha values for sports, funnel counters). While front-loaded with the key purpose, it could be more concise by moving some details to a sub-document.

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 9 parameters, no output schema, and the tool's complexity, the description is comprehensive. It explains the output structure (by_segment, fed_candidates, diagnostics) and internal logic, providing enough context for an agent to use it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra context for several parameters (e.g., explaining min_kelly is half-Kelly, slippage_pp details, min_partition_leg_kelly usage), adding value beyond the schema.

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

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

Description clearly states the tool scans top Polymarket markets to find opportunities where Pipeworx data disagrees with market price, and is built for 'what should I bet on today'. This distinguishes it from sibling tools 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 provides clear context on when to use the tool (e.g., discovering opportunities without paging). It details the three segments and the tradeable-edge knobs but does not explicitly contrast with siblings or state 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?

The description aligns with annotations (readOnlyHint, idempotentHint, destructiveHint=false) and adds valuable behavioral context: snapshot TTL (60 days), data gaps when no scan occurs, and decay calculation basis (daily closes, not intraday). No contradictions.

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

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

The description is verbose and dense, mixing purpose, response format, and limits into a single paragraph. It could benefit from structured elements like bullet points. Some redundancy exists (e.g., explaining response fields in detail).

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

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

With no output schema, the description thoroughly explains return values (tracked[], expired[], snapshot_dates[]) and their fields. It also covers limitations (TTL, decay computation). This provides sufficient completeness for an agent to understand the tool's output.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description adds minimal extra meaning (e.g., 'snapshot family' for window), but mainly reiterates defaults and constraints. 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 provides edge persistence and decay telemetry from daily snapshots, answering specific questions about edge duration and shrinkage. It distinguishes itself from siblings like polymarket_edges and polymarket_arbitrage by focusing on historical behavior rather than current data.

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

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

The description gives context on when to use the tool (e.g., determining if an edge is fresh vs old) and explains the significance of edge age. However, it does not explicitly state when to avoid this tool or recommend alternatives, which would improve guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent. The description adds context about order book walking, return fields, and risks like forced directional risk, which enriches 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 lengthy but well-structured with clear sections and packed with essential details. A minor cut could be made to overly verbose phrases, but overall it is efficient for the 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?

The description lists all significant return fields and explains risks for partial fills. Lacks explicit error handling mentions but is sufficiently complete for a read-only check tool given no output schema.

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

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

Schema coverage is 100%, but the description adds value by explaining size_usd interpretation differences between modes and side default logic for baskets, going 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 checks 'Realizable-vs-theoretical edge against live CLOB order-book depth' and distinguishes between two modes (single-market and basket). It explicitly relates to sibling tools polymarket_arbitrage and polymarket_edges, making its unique purpose unambiguous.

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

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

The description explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and warns about partial fill risks, providing clear when-to-use and considerations.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it explains the tool is safe, that it may return compatibility warnings, and details the safety fields (compatibility_warning, temporal_alignment, skipped counters). It does not contradict annotations.

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

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

The description is well-structured, starting with purpose, then modes, response, and safety fields. It is slightly verbose but every sentence adds value. It front-loads the key information. Could be trimmed slightly without losing meaning, but it's effective.

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

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

Given the complexity (two venues, two modes, safety warnings, alignment checks) and no output schema, the description covers all necessary aspects: response format (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters), edge cases, and limitations. It is complete.

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

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

Input schema has 3 parameters with 100% coverage. The description adds semantic value: it explains the two modes, lists all 10 pre-mapped topics, provides example values (e.g., 'KXFED-26OCT'), and describes how explicit tickers override the topic-mapped side. This goes beyond the schema.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison and explicitly mentions the two modes ('topic' and explicit tickers). The verb 'compute spread' and resource 'cross-venue' are specific.

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

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

The description provides explicit guidance on when to use the tool (to compare same outcome across two prediction markets) and when not to use it (when bet shapes are not equivalent or temporal alignment is false). It warns that most pre-mapped topics return compatibility warnings, setting realistic expectations. This is thorough and helps the agent decide.

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

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

Annotations already declare readOnlyHint=true. The description adds context about scoping (anonymous IP, BYO key hash, account ID) 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?

Three front-loaded sentences, no fluff. 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 covers scoping and pairing. Could mention return format, 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 a clear parameter description. The description adds usage context: omitting key lists all keys.

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

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

The description clearly states the tool retrieves a saved value or lists keys, differentiating it from 'remember' and 'forget'.

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

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

Provides explicit when-to-use (look up stored context) and when-not-to (re-deriving), and pairs with 'remember' and 'forget' as alternatives.

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

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds the mark_read behavior and confirms the feed is persisted. No contradiction with annotations.

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

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

The description is a single paragraph of about 5 sentences, front-loading the primary purpose. It is concise and every sentence adds value, though slightly denser than necessary.

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

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

Given the tool has 5 parameters and no output schema, the description explains the return format (source, citation_uri, payload) and polling behavior, making it complete enough for an agent to understand 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%, but the description adds important context: explains the meaning of type (e.g., 'sec_8k'), since (ISO timestamp), and the effect of mark_read. This adds value beyond the schema.

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

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

The description clearly states it pulls fired events from subscription feed, returns recent alerts with source, citation_uri, and raw payload. It distinguishes itself from sibling tools like list_subscriptions and subscribe by focusing on reading the feed.

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

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

Describes polling works fine and mentions the same feed via HTTP, implying usage context. Does not explicitly list exclusions or alternatives, but the context is clear enough for an agent to decide when to use this tool.

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

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

Annotations already mark it as read-only, non-destructive, idempotent, and open-world. The description adds significant behavioral context: parallel fan-out to multiple sources, GDELT→GNews fallback, USPTO soft-fail, and return structure including total_changes and citation URIs. 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 a single paragraph that front-loads with example queries before explaining sources and parameters. Every sentence adds value, though it is dense and could be slightly more concise by separating the parameter explanation into a clearer list or shorter sentences.

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

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

Despite lacking an output schema, the description mentions the return structure (changes[] grouped by source, total_changes count, pipeworx:// URIs). It covers all critical aspects: purpose, data sources, fallback behavior, parameter guidance, and differentiation from sibling tool. For a multi-source aggregation tool, this is highly complete.

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

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

Schema coverage is 100%, but the description adds substantial value: explains `since` with examples ('2026-04-01', '7d', '30d') and recommends '30d' or '1m'. Clarifies that `value` accepts ticker or CIK. Describes that `type` is currently limited to 'company'. This enables correct parameter usage beyond the schema's basic descriptions.

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

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

The description clearly states the tool provides a change feed for a company, listing specific sources (SEC, GDELT/GNews, USPTO) and example queries. It explicitly distinguishes itself from sibling tool 'entity_profile', fulfilling the distinction requirement.

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

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

Explicitly provides when-to-use examples (e.g., 'latest on Y') and when-not-to-use (use entity_profile for static profile). Also explains fallback behavior for news sources, offering clear guidance on selecting this tool over alternatives.

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

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

Discloses scoping by identifier, persistence differences between authenticated and anonymous users, and pairing with recall/forget. Annotations already indicate idempotent and non-destructive nature, but description adds useful context.

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

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

Description is 5 sentences, front-loaded with purpose, and efficient. Slightly verbose in the middle but overall well-structured.

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

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

For a simple key-value tool with no output schema, description covers purpose, usage, behavior, and relationships with siblings. 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 coverage is 100%, parameters are well-described. Description adds value with example key formats, but the baseline is met without needing much extra.

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

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

The description clearly states the tool saves data for reuse, provides examples (resolved ticker, target address, user preference), and distinguishes from siblings by referencing 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 states when to use ('when you discover something worth carrying forward') and how it pairs with other tools. Could be more explicit about when not to use.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds valuable context: internal cascading of lookups, replacement of 2-3 manual steps, and detailed output per type including citation URIs. No contradiction with annotations.

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

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

The description is concise, front-loaded with examples, and efficiently structured. Every sentence adds value without redundancy. At 80 words, it packs necessary information without being verbose.

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

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

Despite lacking an output schema, the description fully covers return values for both types (ticker, CIK, company name, citation for company; RxCUI, ingredient, brand, citation for drug). It also explains internal behavior and scope, making it complete for selection and invocation.

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

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

Schema has 100% coverage with descriptions for both parameters. The description adds semantics by giving concrete examples of valid values ('AAPL', '0000320193', 'ozempic') and explaining how each type maps to specific identifiers, exceeding what the schema provides.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical identifiers. It provides specific query examples ('What's the ticker for...', 'find the CIK for...') and explicitly distinguishes it from sibling tools by advising to '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 gives clear guidance on when to use the tool ('Use FIRST') and lists supported types (company, drug) with return details. It does not explicitly state when not to use it, but the context is strong enough to infer alternatives when an ID is already available.

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 significant behavioral context beyond annotations: it explains the tool probes each entity with 'ai_visibility_check', ranks by score, and returns a ranked list with score, confidence, signal density. It also notes that the first entity is the subject for narrative. No contradictions with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false).

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

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

The description is three well-structured sentences. The first sentence states the purpose, the second explains the process, and the third provides a concrete use case. No unnecessary words, but could be slightly more concise by merging sentences.

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 describes the return format (ranked list with score, confidence, signal density). Input parameters are fully covered in the schema. The complexity (4 params, 1 required) is well-addressed. The description is complete for an agent to understand the tool's purpose and 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 description coverage is 100%, so baseline is 3. The description adds value by specifying that the first entity is treated as the 'subject' for narrative, which is not in the schema. It also gives context that '_apiKey' is only needed for 'anthropic' model, reinforcing 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 uses a specific verb 'Compare' with a clear resource 'AI visibility across multiple entities.' It distinguishes itself from sibling tools like 'ai_visibility_check' (single entity) and 'compare_entities' (generic comparison) by explicitly stating it ranks and surfaces which entity is most/least recognized.

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') and an example question. It does not explicitly exclude scenarios or name alternative tools for specific needs, but the context implies it is for multi-entity comparison, differentiating from single-entity probes.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds valuable behavioral details: fans out across two services, returns summary block and details, warns about potential 5-30s timeout on BundlePhobia first measurement, and how partial failures are handled (sources_failed field). 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 informative but somewhat verbose. It front-loads the main purpose and usage, then details return values and limitations. Could be slightly more concise, but efficiently communicates all necessary 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 no output schema, the description thoroughly explains the return format (summary block with specific fields, per-advisory detail, links, alternative versions) and covers failure modes (timeout handling). Provides a complete picture for the agent.

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

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

Schema coverage is 100% with clear descriptions for both parameters (package and version). The description does not add significant meaning beyond what is already in the schema, so 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 it is a composite check for npm packages, specifying the verb 'scan' and the resource 'npm package'. It distinguishes from siblings by noting the NPM-only scope and referring to alternatives 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 states when to use: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also gives exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', guiding the agent when to pick another tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond these: it notes the tool is 'keyless' (no authentication needed) and 'offline' (no network required), and describes the return format (emoji with shortcodes). There is 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 extremely concise: two sentences that front-load the core action and examples, followed by a brief note on key features. Every word earns its place with no redundancy or filler.

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 simplicity of the tool (two parameters, no output schema, no nested objects), the description is complete. It covers the search function, example keywords, return type, and special characteristics (keyless, offline). No additional information is needed for correct invocation.

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

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

The input schema has 100% coverage and describes both parameters ('query' as a keyword, 'limit' with default). The description adds concrete examples ('party', 'money', 'animal') and hints at the output structure (emoji with shortcodes), which enriches meaning beyond the schema alone. Not quite a 5 because the schema already captures essentials.

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

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

The description clearly states the tool searches emoji by keyword/name and returns matching emoji with shortcodes. It is specific about the verb ('search'), resource ('emoji'), and scope ('by keyword/name') with examples. While it doesn't explicitly differentiate from the sibling 'emoji_lookup', the purpose is unmistakable.

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

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

The description implies usage for simple emoji searches via keyword and mentions it is keyless and offline, but it does not provide explicit guidance on when to use this tool versus the sibling 'emoji_lookup' or any alternatives. The context is clear but lacks exclusionary or comparative 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?

Discloses beyond annotations: returns top-N passages with offsets and scores, specifies embedding model (BGE-base-en), window size (500-char overlapping), and a 200K char cap with truncation flag. 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?

Single paragraph front-loads purpose, then usage, then technical details. No superfluous information; 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?

Even without an output schema, the description explains return format (passages with offsets and scores), covers truncation behavior, and integrates well with the sibling tool ecosystem. Comprehensive 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, but the description adds critical context: examples for query, default and range for limit, and max chars for text. This significantly aids correct parameter 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?

Clearly states 'semantic search INSIDE a fetched record,' specifying a distinct verb+resource. Distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with general search tools.

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

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

Explicitly advises when to use: 'when the record is too big to cram into the prompt' and describes how it pairs with ask_pipeworx_grounded, providing clear context for tool selection.

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

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

The description adds significant behavioral context beyond annotations: OAuth requirement, return value (id), delivery channel behaviors (feed always on, email/SMS with constraints like phone verification and 10/day cap, webhook with HMAC and auto-disable after 10 failures). No contradiction with annotations (idempotentHint=true is not contradicted).

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

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

The description is relatively long but front-loaded with the essential purpose. It uses bullet points and examples effectively for the complex subscription types and delivery options. Every sentence adds value, though a slightly more compact structure could be achieved without losing clarity.

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

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

Given the tool's complexity (3 params, nested objects, multiple types, no output schema), the description covers prerequisites, type-specific parameters, delivery behaviors, and limitations adequately. It could be improved by mentioning typical error cases or how to handle failures, but it is sufficient for an AI to correctly invoke the tool.

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

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

With 100% schema coverage, the description adds substantial value by explaining the type enum values with real examples (e.g., sec_8k with items, polymarket_edge with topic), detailing the params object for each type, and elaborating on delivery channel properties with conditions (e.g., phone verification, webhook HMAC). This goes well beyond the schema's 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 starts with a clear verb+resource: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation and providing specific subscription types and delivery channels.

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 specifies prerequisites ('Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).') and details when to use each type and delivery channel. However, it does not explicitly state when not to use this tool versus alternatives, only implicitly through the OAuth requirement and subscription types.

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, so the description carries less burden. The description adds context about the output format (category-bucketed example questions with tool shapes) and topic filtering behavior, but this is not extensive. 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 front-loaded with common example queries, making it easy to scan. It is relatively long but every sentence adds value. Could be slightly more concise, but overall well-structured.

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

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

Given the simplicity of the tool (1 optional parameter, no output schema, rich annotations), the description covers the purpose, usage, parameter semantics, and expected output. It is complete enough for an agent to understand when and how to invoke it.

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 optional parameter. The description expands on the schema's description by listing the specific topic values ('finance, pharma, economics, real-estate, betting, weather, government, science, news') and explains the effect of omitting vs. passing a topic, adding meaningful guidance.

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

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

The description clearly states it is the onboarding entry point, returning category-bucketed example questions with exact tool and argument shapes. It distinguishes from siblings like ask_pipeworx and discover_tools, and explicitly says to use it first when the agent does not know what Pipeworx can do.

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 this tool: 'first when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It implies when not to use (after onboarding), but does not explicitly exclude other scenarios, leaving some ambiguity.

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

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

Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds that rows are deactivated not deleted, preserving historical events, and that ownership is enforced.

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

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

Two sentences, no redundant words, key information front-loaded.

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

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

For a tool with one parameter and no output schema, the description covers purpose, ownership, effect, and historical impact completely.

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 does not add new parameter information beyond 'id' being the subscription uuid. Baseline score 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 uses the specific verb 'Cancel' and resource 'subscription by id', clearly distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement ('only cancel your own subscriptions') and the deactivation behavior, but does not directly compare to alternatives like 'unsubscribe' vs 'forget' or '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 adds behavioral context beyond annotations: it details the two processing pipelines, the return fields (verdict, actual value with citation, reasoning), and performance benefit (replaces 4-6 calls). Annotations already indicate readOnly, openWorld, idempotent, and non-destructive; description does not contradict them and provides richer behavioral insight.

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

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

The description is relatively long but well-structured: it starts with query examples, states the main use case, then explains the two processing paths and return format. Every sentence adds value; there is minimal redundancy. It could be slightly shorter by removing some example phrasings, 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 tool has only 2 parameters and no output schema, the description thoroughly covers what the agent needs: the type of input, processing logic, expected output (verdict types, value with citation, reasoning), and when to use each pipeline. It is fully self-contained for an agent to decide invocation and interpret results.

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

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

Schema coverage is 100%, but the description adds meaning: it explains that tolerance_pct overrides the default implied by wording (capped at 5), and it clarifies the claim parameter with examples. This provides operational nuance beyond the schema alone, helping the agent set appropriate parameters for hallucination detection.

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

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

The description uses specific verbs like 'validate', 'verify', 'confirm or refute' and explicitly ties to natural-language claim verification against authoritative sources. It distinguishes itself by specifying two processing paths (SEC structured for company-financial claims, grounded pipeline for all others), which differentiates it from sibling tools that are more general research or lookup 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 clearly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the decision logic between the structured SEC path and the grounded pipeline. However, it does not explicitly mention when NOT to use this tool (e.g., for non-factual queries) or directly contrast with specific sibling tools, though the purpose is distinct enough.

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