Pipeworx Faq

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds useful context on the scope of questions (platform meta) without contradicting annotations.

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

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

Two sentences plus an example, no wasted words. The structure front-loads the purpose and uses a clear example to illustrate usage.

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) and the annotations covering safety, the description fully covers what an agent needs to understand its purpose and usage.

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

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

Only one parameter 'question' with 100% schema description coverage. The description does not add semantic detail beyond the schema's own description, so baseline 3 applies.

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

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

The description clearly states 'Answers questions about Pipeworx itself' and enumerates specific topics (pricing, rate limits, routing, etc.), distinguishing it from sibling tools that address other domains or actions.

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

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

Explicitly says 'Use this for meta questions about the Pipeworx platform or gateway' and provides a concrete example. While it doesn't list exclusions, the sibling list implies alternatives for non-meta queries.

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 meaningful context: the default free model, the need for BYO Anthropic key, and the return format (per-model score, confidence, signals, raw_response).

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?

Four sentences, each providing essential information with no redundancy. The main action is front-loaded, and supporting details (default model, optional key, return type, use cases) follow logically.

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

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

For a probe tool with 4 fully documented parameters, no nested objects, and no output schema, the description covers purpose, usage, return format, and contextual examples. It is complete enough for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the purpose of _apiKey ('BYO key — you pay Anthropic directly'), the default model, and how context can disambiguate common names, going beyond the schema's field 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 specific verb ('Probe') and resource ('LLMs for what they know about a business / brand / product / topic and score visibility'), clearly distinguishing it from sibling tools like 'ask_pipeworx' or 'entity_profile' which serve different functions.

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

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

The description explicitly states use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional _apiKey parameter. However, it does not explicitly exclude scenarios where alternative tools might be better.

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 read-only, idempotent, safe behavior. The description adds behavioral context beyond annotations: it routes to 5,432 tools, fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and is 'one fast call'. No contradiction with annotations.

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

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

The description is verbose, with extensive redundancy: the list of domains ('SEC filings, FDA drug data...') and the later trigger phrases ('what is', 'look up'...) repeat the same guidance in different words. While front-loaded with a strong first sentence, it would benefit from trimming to the core message and a few key examples.

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 required parameter, no output schema) and rich annotations, the description covers all necessary context: what it does, when to use, when not to use, alternatives, and even output behavior. No significant gaps for the agent to invoke it correctly.

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

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

Schema coverage is 100%, so the description doesn't need to repeat parameter definitions. It adds value by supplying semantic categories and example questions (e.g., 'current US unemployment rate', 'Apple's latest 10-K') that clarify what kinds of natural-language queries are appropriate, exceeding the baseline expectation.

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 answers questions about real-world data by routing to 5,432 tools across 1,411 sources and returning structured answers with citation URIs. The phrase 'PREFER OVER WEB SEARCH' and explicit mention of alternatives like ask_pipeworx_grounded distinguish it 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?

Provides explicit guidance: 'START HERE for most questions', 'Use whenever the user asks "what is", "look up"...' and identifies when to step up to grounded or deep_research. Includes concrete examples and mentions news/breaking-news routing, leaving no ambiguity about 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?

Beyond annotations (read-only, idempotent), the description discloses that the tool is an experimental edge with candidate routing improvements that can be toggled live. It clarifies the current state ('no candidate is active') and that it is a fully working router, not a stub. This provides substantial 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 sentences, dense with information, and front-loaded with the key beta/identical-router context. Every sentence earns its place, with no redundancy or fluff.

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

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

For a beta variant of a known tool, the description provides all necessary context: it is identical to ask_pipeworx, can have live routing changes, and currently behaves exactly like the stable version. It references the sibling for response shape and usage, which is sufficient given the agent has access to ask_pipeworx's full 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?

Schema description coverage is 100%, with all six parameters well-documented as aliases for the question. The description only says 'same arguments' as ask_pipeworx, adding no additional meaning beyond what the schema already provides. Thus, 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 identifies this as the beta version of ask_pipeworx, a universal router with the same 5,432 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx and other siblings like ask_pipeworx_grounded by focusing on experimental routing improvements.

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

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

The description explicitly states when to use it: 'when you want the newest routing.' It also implicitly distinguishes from the stable ask_pipeworx by referring to it as the comparison baseline. However, it does not explicitly say 'use ask_pipeworx for stable production' or provide a when-not-to-use scenario, so it falls short of a full 5.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses the tool's grounded extraction mechanism, return structure including evidence and confidence, all possible refusal reasons, and the extra LLM call cost. This significantly enriches the agent's understanding of behavior.

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

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

The description is dense but well-structured, front-loading the core purpose and then covering mechanism, output, refusal logic, usage context, and cost trade-off. Each sentence adds value, though it is somewhat long for a description.

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 grounded-answer tool, the description is comprehensive: it explains the routing, extraction constraint, exact return format, refusal reason enum, use cases, and comparison to the sibling tool. No output schema is needed because the description details the return structure.

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

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

Schema coverage is 100% with all parameters documented as aliases for the natural language question. The description doesn't add significant parameter semantics beyond the schema, but the tool is simple (single question input), so 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 the tool's purpose: a 'hallucination-resistant answer mode for high-stakes reads' that extracts answers using only tool results. It distinguishes itself from siblings, especially ask_pipeworx, by describing its grounded extraction behavior and structured output with refusal reasons.

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 answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also provides an alternative: 'prefer ask_pipeworx for casual lookups,' making the usage decision 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 (readOnlyHint, openWorldHint, idempotentHint) already indicate safe, read-only behavior. The description adds extensive detail on resolution logic, fan-out, edge cases, and safety mechanisms, more than compensating for any lack of annotation depth.

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

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

The description is very long with multiple paragraphs and excessive detail (e.g., fan-out examples, classifier list). While front-loaded with purpose, it is not concise.

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

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

Given the tool's complexity (3 parameters, no output schema), the description covers all behavioral aspects, edge cases, and safety checks comprehensively.

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

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

Schema covers all parameters (100% coverage). Description adds context on 'market' input types and 'depth' options but does not significantly enhance semantics 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 the tool researches Polymarket bets by pulling Pipeworx data, specifying inputs and outputs. It distinguishes the tool's purpose but does not explicitly differentiate from siblings like polymarket_edges or ask_pipeworx.

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

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

Explicit use cases are given ('should I bet on X', etc.), but no direct comparison to sibling tools or when not to use this tool. Implied usage context but lacks exclusions.

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

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

Beyond annotations (readOnly, openWorld, idempotent, not destructive), the description details data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, return data (paired data + citation URIs), and sorting behavior. This provides rich behavioral context not captured by 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 efficiently organized: starts with example triggers, states core purpose, explains data per type, and notes sorting and output format. Every sentence adds value, though it could be slightly tightened by merging some redundant phrases.

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

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

Given the tool's moderate complexity (2 params, no output schema), the description covers all necessary aspects: when to use, what data is fetched per entity type, how results are sorted, and output structure. It fully informs an agent 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?

Schema coverage is 100% with clear parameter descriptions in the schema itself. The free-text description reinforces the parameter meanings (e.g., values array for tickers or drug names, min/max items) but adds no new semantic details beyond what the schema already provides.

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

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

The description begins with concrete user queries and clearly states the tool's purpose as side-by-side comparison of 2-5 companies or drugs in one parallel call. It explicitly distinguishes from alternatives by stating 'ALWAYS PREFER over sequential single-pack lookups' and notes it replaces 8-15 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?

The description provides explicit guidance on when to use the tool (comparing entities) and recommends it over sequential lookups. However, it does not explicitly mention alternative tools like 'entity_profile' for single-entity deep dives, leaving some ambiguity for non-comparison needs.

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

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

Even though annotations already declare readOnlyHint and idempotentHint, the description adds substantial behavioral context: parallel decomposition, findings packet with verbatim evidence, gaps[] for unanswered facets, contradictions[] detection, hop field, semantic excerpting, account requirements, and expected latency. No contradiction with annotations is present.

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

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

The description is long but well-structured, front-loading critical auth requirements and then organizing details into logical clusters. While some redundancy exists (contradictions[] mentioned twice), the density is warranted given the tool's complexity and the absence of an output schema. It could be tightened, but it remains navigable.

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 must explain the return format, and it does thoroughly: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri. It also covers failure modes (empty gaps for non-catalog topics), timing expectations, and paid-tier details. This is complete for a 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?

The input schema already provides complete descriptions for both parameters (100% coverage), so the baseline is 3. The description adds meaningful context beyond the schema by explaining what 'depth' levels actually do ('standard' re-angles unanswered gaps, 'thorough' chases leads) and that 'question' can be broad/multi-part. This extra semantic detail 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's purpose: 'Grounded multi-source research across Pipeworx's 1411 STRUCTURED data sources' in one call. It uses a specific verb ('research'), names the resource (structured data sources), and distinguishes itself from siblings by explicitly noting it is NOT open-web search and by comparing to ask_pipeworx.

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

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

Usage guidance is explicit and comprehensive. It states when to use this tool (broad/multi-part questions over structured data), when to use alternatives ('For a single lookup use ask_pipeworx'), and even handles edge cases like breaking news and authentication status ('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 already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value beyond annotations by explaining that results include full input schemas with curated examples, are 'ready to call directly,' and no second schema lookup is needed. 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 front-loaded with the core purpose. The list of example domains is long but helps clarify scope. Every sentence adds value; no redundancy. Could be slightly trimmed, 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?

Despite no output schema, the description fully explains return values: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It also clarifies that results are 'ready to call directly' and 'no second schema lookup needed.' Covers all essential aspects for a discovery tool.

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

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

Schema coverage is 100% with all parameters well-described. The description adds context by explaining the 'query' parameter accepts aliases (task, q, description, search) and providing example queries. It also specifies the default and max for 'limit' (20, 50).

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 (find, browse, search, look up, discover) and identifies the resource (tools). It lists many example domains (SEC filings, FDA drugs, etc.) and clearly distinguishes from sibling tools like 'deep_research' or 'ask_pipeworx' by emphasizing discovery over direct execution.

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

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

The description explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also provides context for when to use (browsing, searching, looking up). While it doesn't list alternatives explicitly, 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 already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral context: fans out across multiple sources, soft-fail for patents, returns specific fields and 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?

Single paragraph densely packed with information, front-loaded with example queries. All sentences are useful, but readability could be improved with structure (e.g., bullet points). Still concise given 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?

Despite no output schema, the description thoroughly covers inputs, sources, return fields, limitations (patents soft-fail, names not supported), and includes example URIs. Complete for a complex tool.

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

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

Schema coverage is 100% with both parameters described. Description adds context: ticker or CIK input, names not supported, and clarifies that CIK must be zero-padded. Adds meaning beyond schema.

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

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

The description clearly states the tool returns a 'full cross-source profile of a US public company in ONE parallel call.' It lists example queries and specifies the output includes CIK, filings, fundamentals, patents, news, and LEI, distinguishing it from chaining single-pack lookups.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also says names not supported, directing to use resolve_entity first. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true; description adds 'delete' (consistent) and 'clear sensitive data' context, but does not expand beyond what annotations convey.

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

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

Two concise sentences, front-loaded with verb and resource. No wasted words.

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

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

For a simple delete tool with one param and no output schema, description adequately covers use cases and pairing. No missing critical elements.

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

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

Schema coverage is 100%, baseline is 3. Description mentions 'by key' but adds no extra meaning beyond schema's 'Memory key to delete'.

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

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

Clear verb 'delete' and resource 'stored memory'. Distinguishes from siblings 'remember' and 'recall' by mentioning pairing, making purpose 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?

Explicit when-to-use cases: stale context, task done, clear sensitive data. Also hints at pairing with siblings. Lacks explicit exclusions or alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds process details (fetches, extracts, emits markdown) which are consistent with annotations. No contradictions.

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

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

The description is concise with two sentences and a usage note. It is front-loaded with the main purpose and every sentence adds value without redundancy.

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

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

Given the tool has 2 parameters, no output schema, and good annotations, the description is fairly complete. It explains the output format and placement, plus use cases. A minor gap is error handling, 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%, but the description adds useful context: for 'url' it says 'full URL of the site to summarize', and for 'max_links' it specifies default (25) and max (50) values not in 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 generates an llms.txt file for a given URL, specifying the output format and use cases. It distinguishes itself from sibling tools by its specific 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 provides explicit use cases (indexing client sites, drafting for own project, auditing competitors) and context. It doesn't explicitly state when not to use or mention alternatives, but the guidance is clear enough.

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

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

Annotations already declare readOnlyHint and destructiveHint false, so safety is covered. Description adds return field details but no extra behavioral context like pagination or rate limits. Adequate given annotation coverage.

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

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

Two concise, front-loaded sentences. First states purpose, second gives usage guidance. No wasted words.

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

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

With no output schema, the description lists return fields, which is helpful. Mentions the optional parameter indirectly. Lacks mention of pagination or limits, but tool is simple and context suffices.

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

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

Schema coverage is 100% for the single parameter. Description does not add meaning beyond the schema, meeting the baseline for high coverage.

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

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

The description clearly states 'List the caller's active subscriptions' and enumerates return fields, providing a specific verb and resource that distinguishes it from siblings like subscribe/unsubscribe.

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

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

Explicitly states when to use: 'review what you're monitoring before adding more' and 'find an id to cancel'. Clear context, though no explicit exclusion of alternative scenarios.

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

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

Annotations provide no useful safety signals (all false), so the description carries the full burden. It discloses rate-limiting (5 per identifier per day), that it is free and doesn't count against tool-call quota, that the team reads digests daily, and that signal affects roadmap. It also instructs to avoid pasting end-user prompts. This goes well beyond the annotations.

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

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

The description is about 120 words and is well-structured: it starts with the core purpose, then use cases, exclusions, a disambiguation not, message guidance, and behavioral notes. Every sentence serves a purpose, and the information is front-loaded rather than buried.

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 feedback tool with three parameters (one nested object) and no output schema, this description covers all essential context: what to report, when to use it, boundary conditions (other MCP servers), rate limits, quota behavior, and message style. The absence of an output schema is acceptable because the return value is likely a simple confirmation; the description sufficiently covers why the tool exists and how 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 coverage is 100%, so the baseline is 3. The description adds extra value by telling the user to describe issues in terms of Pipeworx tools/packs and not to paste end-user prompts, which directly informs how to fill the message parameter. It doesn't add new meaning to the type or context fields, but the message guidance is a meaningful supplement.

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: to tell the Pipeworx team about something broken, missing, or needing to exist. It uses an imperative verb ('Tell') and a specific resource (the Pipeworx team), and the rest of the description distinguishes it from sibling tools by positioning it as the feedback channel for this specific MCP connection.

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

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

The description provides explicit when-to-use guidance: use for bugs, feature/data_gap requests, or praise. It also gives a clear exclusion (do not use for tools from other MCP servers, file with that server instead) and a disambiguation rule for identifying Pipeworx tools ('Pipeworx tool names are the ones this connection lists'). This is textbook usage guidance.

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

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

Annotations already mark the tool as readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns gateway URL, plugin links, and suggestions, which is consistent. 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?

Two sentences with no redundant words. Front-loaded with purpose, includes example. Every sentence earns its place.

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

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

For a simple read-only tool with one optional parameter, the description fully explains what to expect and how to use it. No output schema needed. Annotations cover behavioral traits.

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?

Parameter 'client' is fully documented in the input schema with examples. The description reinforces with an example call. Since schema coverage is 100%, the description adds marginal value but the example is helpful.

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

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

Description clearly states it provides step-by-step instructions for connecting AI clients to Pipeworx, listing specific clients and outputs (gateway URL, plugin links, suggestions). It distinguishes from siblings like about_pipeworx and ask_pipeworx.

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

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

Description includes an explicit example of invocation and specifies the return content. It does not explicitly exclude use cases or name alternatives, but the example and context make usage straightforward for an agent.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds value by disclosing self-aggregating nature, no PII, and caching behavior (5min-1h). 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?

Three sentences and a bulleted list, front-loaded with the core purpose. Every sentence adds information. No wasted words.

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

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

For a simple tool with one optional param and no output schema, the description covers all necessary aspects: return values, use cases, data source, caching, and privacy. Complete.

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

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

Schema coverage is 100% with enum descriptions. Description adds meaningful context: explains the trade-off between windows (hot vs steady-state) and defaults. Goes beyond schema.

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

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

The description clearly states it returns 'top tools, top packs, and total call volume over a recent window.' The verb 'returns' and specific resource make purpose unambiguous. It distinguishes from siblings like discover_tools by focusing on trending usage 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?

Explicitly lists three use cases and explains window trade-offs (shorter for hot, longer for steady-state). Lacks explicit when-not-to-use or alternatives, but provides 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 already declare readOnlyHint=true and openWorldHint=true, indicating safe read operations. The description adds behavioral context: it uses Jaccard similarity, drops placeholder slugs, and performs fill checks against live CLOB depth. No contradictions with annotations. Extra details like 'deviations >3pp emit a signal' enrich transparency, but annotations cover safety profile well.

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

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

The description is dense and well-structured with clear sections (modes, semantic anchor, partition filter, response, fill check). It is front-loaded with the main purpose. However, some details like exact Jaccard threshold and 3pp deviation could be slightly more concise. Overall, every sentence earns its place.

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

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

No output schema exists, so the description carries full burden of explaining the response, which it does explicitly: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and partition check details. It covers edge cases (placeholders, low similarity) and fill check instructions. The description is thorough for a complex arbitrage detection tool.

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

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

Schema description coverage is 100% with both parameters described. The description adds significant extra meaning: explains the difference between event and topic modes, provides example inputs (e.g., 'fed-decision-may-2026'), describes default behavior with no args, and clarifies what each mode returns. This goes beyond the brief 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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) and differentiates from sibling tools like polymarket_fill_risk. The verb 'find' with specific methods and resource 'Polymarket arbitrage opportunities' makes the purpose precise.

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

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

The description explicitly tells when to use each parameter: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also advises when not to trade (realizable_edge_pp ≤ 0) and suggests using polymarket_fill_risk for custom sizing, providing clear alternatives.

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

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

The description thoroughly explains the tool's read-only nature (consistent with annotations), caching behavior (1h KV), response structure (segments, diagnostics), and how edges are computed. It adds significant context beyond annotations, such as the 24h-move warning and Fed bet disclaimer.

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 detailed but overly long and dense, with extensive model explanations. While informative, it could be more concise. The purpose is front-loaded, but the verbosity may reduce efficiency for agent parsing.

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

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

Given the complexity (9 parameters, no output schema, multiple segments), the description covers all necessary aspects: response structure, knob effects, diagnostics, caching, and limitations. It is fully self-contained for agent usage.

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

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

With 100% schema coverage, the baseline is 3. The description adds meaningful practical guidance (e.g., 'Set to 5000 to drop thin-book opportunities'), which enhances understanding beyond the schema descriptions. Minor marks off for some redundancy.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with price, and it details three model families. However, it does not explicitly distinguish itself from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, which could cause confusion about when to use which.

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

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

The description explains the tool is for discovering betting opportunities and provides several 'knobs' (min_liquidity, max_spread_pp, etc.) with usage guidance. It lacks explicit 'when not to use' instructions or comparison to alternatives, but the context is clear enough for agents to decide.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral details: 60-day snapshot TTL, decay from daily closes not intraday, and snapshot gaps. No contradiction found.

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

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

The description is detailed but front-loaded with the core question and answer. Every sentence serves a purpose, though it is slightly verbose. Structurally sound with clear sections for args, response, and limits.

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

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

Despite no output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and limits. It compensates fully for the missing schema, providing complete context for an complex tool with two parameters.

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

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

Schema covers both parameters with descriptions (100% coverage). The description adds minor context (e.g., 'snapshot family' for window) and clarifies default/max values, but does not significantly enhance beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots', answering a specific question about edge longevity. This distinguishes it from sibling tools like polymarket_edges and polymarket_arbitrage.

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 (to understand edge persistence and decay) and contrasts old vs new edges. However, it does not explicitly mention when not to use it or list alternative tools, though the sibling tools are evident.

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, idempotent, and non-destructive behaviors. The description adds rich context beyond annotations: it walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.), and discloses risks like forced directional risk and thin legs. No contradiction with annotations.

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

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

The description is well-structured with bold headers (SINGLE-MARKET, BASKET) and front-loaded purpose. It is somewhat verbose but every sentence adds value. Slightly more concise could improve, but overall it's appropriate 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?

Given the tool's complexity (two modes, no output schema), the description covers all essential aspects: required parameters, return fields for both modes, risk warnings about partial fills and directional exposure. It provides sufficient detail for an AI agent to understand the tool's behavior and output without needing 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?

Schema coverage is 100%, so baseline is 3. The description adds extra semantics: it explains that market or event is required, defines size_usd differently per mode (max spend vs target proceeds vs settlement notional), and clarifies default side logic for basket mode. This improves understanding beyond the schema.

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

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

The description states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth,' clearly distinguishing between single-market and basket modes. It explicitly contrasts with siblings like polymarket_arbitrage and polymarket_edges by specifying when to use this tool before those actions.

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 context: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround uncapturable, partial basket fills create directional risk) and what not to do, 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?

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds extensive context: response fields (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning conditions, temporal_alignment, skipped counters), and the fact that meaningful spreads require alignment. No contradictions.

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

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

The description is thorough but slightly verbose. It is well-structured with two main modal sections and clear response/field definitions. Every sentence adds value, but minor trimming could improve conciseness.

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

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

Despite no output schema, the description fully explains the response structure and safety fields. It covers edge cases (compatibility_warning, temporal alignment) and provides enough detail for an agent to correctly invoke 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 descriptions cover all three parameters (topic, kalshi_event_ticker, polymarket_event_slug) with examples. The description further clarifies that explicit tickers override topic mappings and provides the full list of topic shortcuts, 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?

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit tickers) and explains the output structure. This specificity differentiates it from sibling tools like polymarket_arbitrage.

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 on when to use each mode, including the warning that most pre-mapped topics return compatibility_warning and are not tradeable. It covers cases where the tool is not useful (non-equivalent bet shapes, temporal misalignment), helping the agent decide when to use alternatives.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral details: the scoping to identifier and the listing behavior when key is omitted. 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 two sentences, no wasted words. It front-loads the main action and then adds contextual details efficiently.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers behavior: retrieval, listing mode, scoping, and pairing with sibling tools. Combined with clear annotations, it is completely adequate.

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 schema description already explains that omitting the key lists all keys. The tool description adds minimal new information beyond the schema, essentially restating it. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all keys when omitted. It uses specific verbs ('retrieve', 'list') and resource ('value', 'keys'). It distinguishes itself from sibling tools like 'remember' and 'forget' by explaining this is the retrieval counterpart.

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

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

The description explicitly says 'Use to look up context the agent stored earlier' and gives examples (ticker, address, research notes). It mentions pairing with 'remember' and 'forget', providing good context. However, it does not explicitly state when not to use it or name specific alternatives, though the purpose is clear enough.

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

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

Description describes a mutation (mark_read:true flags events as read) but annotations declare readOnlyHint=true, creating a direct contradiction that misleads the agent about the tool's idempotency.

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

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

The description is well-structured and front-loaded with purpose, though it could be slightly more concise by combining the multiple sentences about filters and mark_read.

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

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

Complete coverage for a read tool without output schema: describes return fields, filtering, polling suitability, and alternative access, leaving no gaps for typical 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?

The description adds significant value beyond the schema by providing examples (e.g., sec_8k), explaining the effect of mark_read, and describing return fields, all with 100% schema coverage.

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

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

The description clearly states the tool pulls fired events from a subscription feed, describes return fields, filtering options, and distinguishes itself from sibling tools like list_subscriptions by focusing on recent alerts.

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

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

The description mentions polling works and provides an alternative access method, but lacks explicit guidance on when to use this tool versus other related tools (e.g., search tools, subscription management).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, which set expectations. The description adds valuable behavioral context beyond annotations: it fans out to multiple sources in parallel, describes GDELT→GNews fallback, and notes patent soft-failure. 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 example queries, and every sentence contributes useful information. It is slightly long but well-structured. Some redundancy could be trimmed (e.g., repeating fallback details), but overall it efficiently conveys the tool's behavior.

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

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

Given the tool's complexity (multiple sources, fallback, soft-fail) and no output schema, the description provides a complete picture: it explains the sources queried, the return structure (grouped changes, total count, citation URIs), and the `since` parameter format. No gaps are apparent.

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 each parameter already described. The description adds extra semantic value: it clarifies the `since` formats (ISO date vs relative shorthand) and provides a typical monitoring suggestion ('30d' or '1m'). It also explains that `value` can be a ticker or CIK. This adds meaning beyond the schema, justifying a 4.

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

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

The description starts with concrete example queries that clearly illustrate the tool's purpose ('What's new with X', 'updates on Acme'). It specifies the tool provides a change feed for a company across SEC filings, news, and patents within a time window. The description explicitly distinguishes it from the sibling tool 'entity_profile' which provides static profiles, earning a 5.

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

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

The description provides explicit usage guidance, including when to use this tool versus the sibling 'entity_profile'. It also explains fallback behavior (GDELT→GNews) and soft-failure for patents, giving clear context for when the tool is appropriate.

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

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

The description adds value beyond annotations by explaining persistence behavior (authenticated vs anonymous sessions, 24-hour retention for anonymous) and scoping by identifier. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with the purpose. It is slightly verbose but every sentence adds value, making it clear without being overly concise.

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

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

For a write tool with 2 required parameters and no output schema, the description adequately covers storage behavior, scoping, and persistence. No missing critical information.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds examples of key values but does not provide additional semantic meaning beyond the schema.

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

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

The description clearly states the tool saves data for reuse, provides concrete examples (resolved ticker, target address, user preference, research subject), and distinguishes from sibling tools (recall, forget) by explicitly mentioning pairing.

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

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

The description explains when to use the tool ('when you discover something worth carrying forward') and pairs it with recall and forget, but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, signaling safety. The description adds behavioral context by noting that each call 'cascades through several lookup endpoints internally,' which explains potential latency and internal complexity. No contradictions with annotations.

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

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

The description is dense but not verbose. Every sentence serves a purpose: opening examples, usage guidance, type details, and behavioral notes. The information is front-loaded with the most critical usage examples, making it easy to scan.

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

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

Despite lacking an output schema, the description thoroughly explains return values (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand, citation for drug). It covers all necessary information for an agent to understand inputs, outputs, and internal behavior, making it self-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?

With 100% schema coverage, the description still adds substantial meaning. For 'type' it explains the two options and what each returns (e.g., 'company' returns ticker, CIK, company_name, and citation URI). For 'value' it provides concrete examples (AAPL, 0000320193, ozempic) and notes auto-disambiguation, going well beyond the schema's basic descriptions.

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

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

The description begins with concrete example queries like 'What's the ticker for…' and 'find the CIK for…', immediately clarifying that the tool resolves names to identifiers. It clearly distinguishes itself from sibling tools by stating 'Use FIRST whenever you have a name but need an ID.' The supported types (company, drug) and their respective outputs are explicitly listed, leaving no ambiguity.

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

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

The description explicitly states when to use this tool: 'Use FIRST whenever you have a name but need an ID.' It also notes that each call replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly mention when NOT to use it or alternative tools for other scenarios, which would be helpful.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by explaining the internal process: probing each entity with ai_visibility_check, ranking by score, and surfacing most/least recognized. It also specifies the output includes score, confidence, and signal density, which is not in annotations.

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

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

The description is concise—three sentences that efficiently convey purpose, mechanism, and use case. The first sentence immediately states the main function. No unnecessary words; every sentence earns its place.

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

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

Given the tool's complexity (multi-entity comparison, ranking, optional models, API key), the description covers all essential aspects: purpose, input (entities, optional models/context), internal process (probe and rank), and output (ranked list with metrics). Without an output schema, the description adequately explains what the tool returns.

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

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

Schema coverage is 100%, so each parameter has a description. The tool description adds additional semantics for the required 'entities' parameter, clarifying that the first entry is treated as the subject and the rest as competitors. This goes beyond the schema and helps the agent understand the parameter's role. Other parameters are well-described in 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 compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and ranks them by score. It differentiates from sibling tools like ai_visibility_check (single probe) and compare_entities (generic comparison) by specifying the focus on AI presence. The purpose is specific and actionable.

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 concrete use case ('does Claude know about us as well as our competitors?') and context for competitive AI-marketing audits. While it doesn't explicitly state when not to use it, the mention of using ai_visibility_check for individual probes implies the alternative. The guidance is clear but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds significant behavioral context: partial failures with graceful degradation, bundlephobia's first measurement taking 5-30s, and listing sources_failed if it times out. No contradictions.

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

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

The description is well-structured: starts with the composite check purpose, then usage, then detailed return and failure modes. It is slightly long but every sentence earns its place. Could be slightly tighter, but clarity is high.

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 block fields (is_latest, license, etc.) and mentions per-advisory detail, links, alternative versions. It covers the tool's behavior completely for an agent to use effectively.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds minor value by noting that scoped packages are accepted and that version defaults to latest. This is useful but not critical beyond the schema.

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

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

The description clearly states the tool's purpose: a composite check for adding npm packages by fanning out across deps.dev and bundlephobia. It distinguishes from siblings by specifying 'NPM ecosystem only in v1' and referencing alternative tools 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?

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me." It also clarifies when not to use it (PyPI/Maven/Cargo/Go) and directs to deps.dev:version directly.

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

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

Annotations already indicate readOnlyHint, idempotentHint, etc. The description adds valuable behavioral details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation and flagging. No contradiction between description and annotations.

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

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

The description is a single paragraph but well-organized: purpose first, then usage, then technical details. It is efficient with no filler, though could benefit from bullet points for readability. Still, it earns its 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 no output schema, the description explains return values ('top-N passages with character offsets and similarity scores'). It covers limitations (200K char cap, truncation) and technical details. Contextually complete for a search tool.

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

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

Schema description coverage is 100% for all 3 parameters. The description adds extra context: text max ~200K chars, query as natural-language query with examples, limit range 1-20 default 5. This enhances understanding beyond the schema alone.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and provides concrete examples (SEC 10-K, article, tool result). It distinguishes from siblings by mentioning it pairs with ask_pipeworx_grounded, making the purpose specific and unambiguous.

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

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

Explicitly advises 'Use when the record is too big to cram into the prompt' and explains how it saves context. Also describes pairing with ask_pipeworx_grounded, providing clear when-to-use and when-not-to-use guidance relative to sibling tools.

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

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

Description claims a creation action that likely creates a new subscription each call, contradicting the idempotentHint=true annotation, which indicates idempotency. This is a serious inconsistency.

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 front-loaded purpose, but slightly verbose due to detailed examples; still 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?

Covers all aspects: type-specific filters, delivery options, prerequisites, and return value, fully meeting the needs of a complex tool with 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?

Adds significant detail beyond the schema, with concrete examples for each subscription type, delivery channel constraints (10/day SMS cap, phone verification), and webhook signature mechanics, at 100% schema coverage.

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

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

Clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID, distinguishing it from siblings like list_subscriptions and unsubscribe.

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

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

Provides explicit prerequisites (Pipeworx OAuth account), supported types, and delivery channels, but does not explicitly contrast with alternatives like recent_alerts or polymarket_arbitrage.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints. The description adds value by specifying that the tool returns category-bucketed example questions with exact tool and argument shapes drawn from the live catalog, providing behavioral context beyond the annotations.

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

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

The description is a single paragraph but front-loaded with common user queries, then explains the return type and usage. Every sentence is informative and earns its place, though it could be slightly more structured.

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

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

Given the tool has only one optional parameter and no output schema, the description is highly complete. It explains the return content (categorized examples with tool+argument shapes), invocation patterns (no args or topic), and usage context (first-step onboarding). Annotations cover behavioral traits, so no gaps remain.

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

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

Schema coverage is 100% with one optional parameter (topic). The description adds meaning by listing specific focus areas (finance, pharma, economics, etc.) and explaining the effect of omitting the parameter (cross-category spread), which goes beyond the schema's brief description.

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

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

The description clearly states that suggest_questions is the onboarding entry point for learning what Pipeworx can do. It lists example user queries and explicitly says 'Use this FIRST' to discover tool capabilities, distinguishing it from sibling tools like ask_pipeworx and discover_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 provides explicit guidance on when to use this tool: when the agent does not know what Pipeworx can do, or to learn how to call meta-tools. It also explains how to invoke it with no arguments or with a specific topic. It does not explicitly state when not to use it, but the context makes it clear it is for initial exploration.

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 the row is deactivated, not deleted, and that ownership is enforced. Annotations align: destructiveHint false, idempotentHint true. No contradiction. Provides context beyond annotations.

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

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

Two concise sentences with no fluff. Every sentence adds value: action, ownership constraint, behavioral nuance. Perfectly 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 simple tool with one parameter and no output schema, the description covers the effect, side effects (historical data retained), and access control. Completely sufficient for agent 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 schema covers the parameter 'id' fully (100% coverage). The description repeats the schema's description ('Subscription id (uuid) returned by subscribe'), adding no new semantic meaning. Baseline score appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id'), identifies the resource (subscription), and distinguishes from siblings like 'subscribe' and 'list_subscriptions'. Ownership enforcement adds specificity.

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 when to use (to cancel a subscription) and notes that historical events remain accessible via 'recent_alerts', guiding post-cancellation behavior. However, it does not explicitly exclude other scenarios or mention alternatives.

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

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

The description adds significant context beyond annotations, including return values (verdict, actual value, citation, reasoning) and the two pathways (structured vs grounded), without contradicting annotations.

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

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

Well-structured with front-loaded purpose, examples, usage, behavior, and return values. Slightly verbose but not wasteful; sentences earn their place.

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

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

With no output schema, the description explains return values and data pathways adequately. Covers most aspects for a complex tool, though 'pipeworx:// citation' could be clarified further.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining tolerance_pct overrides implied wording, and provides examples for claim, slightly enhancing parameter understanding.

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 verifies natural-language claims against authoritative sources, provides example phrasings, and distinguishes between company-financial claims and other claims, differentiating it from sibling tools.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains behavior for different claim types, but lacks explicit when-not-to-use or alternative suggestions.

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