Opendota

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

Even with readOnlyHint=true, the description adds meaningful behavioral context: passing `_apiKey` triggers external calls to Anthropic with direct cost to the user ('BYO key — you pay Anthropic directly'). It also discloses the return structure ('per-model {score, confidence, signals, raw_response} + a combined view'), which clarifies side effects and output behavior 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 four sentences, each carrying essential information: core function, defaults/cost, return format, and use cases. It is front-loaded with the primary purpose and avoids any fluff or repetition of schema details. No sentence is wasted.

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 moderate complexity (4 params, no output schema), the description covers all important aspects: return format compensates for missing output schema, external dependencies are disclosed, and use cases are provided. Annotations already cover safety, so the description completes the remaining context 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 description coverage is 100%, so the baseline is 3. The description adds value by specifying the default model ('Default model is Workers AI Llama-3.3-70b (free)'), which clarifies behavior when `models` is omitted. It also ties the optional `_apiKey` to the Anthropic model, though this is largely redundant with the schema. This extra context justifies a 4.

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

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

The description clearly states the tool's function: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This is a specific verb+resource+outcome and differentiates it from sibling tools like ask_pipeworx by focusing on LLM knowledge, not Pipeworx-specific data. The listed use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) further anchor its purpose.

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

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

The description provides clear use-context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the default model and the optional Anthropic key, so an agent knows when additional configuration is needed. However, it does not explicitly name alternative tools or state exclusions, so it falls short of 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds context beyond these: it routes across many tools, returns a structured answer, works on every tier, and is 'one fast call'. It also notes it can handle breaking news. This is useful context that complements the annotations without contradiction.

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

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

The description is long but well-structured. It front-loads the key directive ('PREFER OVER WEB SEARCH'), then explains mechanism, provides usage triggers, examples, and alternatives. While somewhat verbose, the length is justified given the tool's broad applicability and 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?

For a tool of this complexity (6 params, no output schema), the description is impressively complete. It covers what, when, why, and how to use, with examples and alternative tools. It discloses the routing behavior and citation output, so the agent has a full picture for invocation.

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

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

Schema coverage is 100% and the only parameter is 'question' with aliases well-documented in the schema. The description does not add meaning beyond the schema, though examples in the description illustrate typical questions. This meets the baseline of 3.

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

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

The description clearly states the tool's purpose: it answers factual questions by routing them to 5,462 tools across 1,419 sources and returns structured answers with citations. It distinguishes itself from siblings by naming alternatives (ask_pipeworx_grounded, deep_research) and specifying its role as the default entry point.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists trigger phrases like 'what is', 'look up', 'find'. It also tells when not to use it and suggests alternatives: ask_pipeworx_grounded for single hallucination-resistant answers, deep_research for broad/multi-part questions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about being a beta with candidate routing improvements enabled live, and the current state with no active candidate, which sets expectations for potential variability. It also discloses it's a full working router with no fallback, beyond what annotations provide.

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

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

The description is four information-dense sentences, each earning its place: definition, current state, usage, and reassurance. It front-loads the key fact about being a beta version of ask_pipeworx, then efficiently provides context. No redundant fluff or trivial details.

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 as a universal router, the description adequately covers what it is, how it differs, and how to use it. It mentions same response shape as ask_pipeworx, which covers return format, and the annotations handle safety. It could have explained what 'routing improvements' means in more detail, but overall it's sufficient for an agent to decide.

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 provides descriptions for all 6 parameters, all aliases for 'question', with 100% coverage. The description adds no extra parameter details, only referencing 'same arguments' as ask_pipeworx, which is already known. Baseline score of 3 is appropriate since schema handles param documentation.

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 'ask_pipeworx_beta' as a beta version of 'ask_pipeworx', specifying it is an identical universal router with the same 5,462 tools, arguments, and response shape. It distinguishes from the stable sibling by mentioning 'candidate routing improvements' and 'experimental edge'. The verb 'ask' implies a query/resolution tool, and the resource is the universal router.

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

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

Explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing', which indicates when to choose this tool over alternatives. It also clarifies that results are compared against the stable router to decide merges, implying this is for testing/evaluating new routing. The mention that it 'Falls back to nothing' reassures that it's a full working router, not a limited approach.

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 that already note read-only and non-destructive behavior, the description discloses the grounding mechanism (using only tool result), the return format with evidence and refusal reasons, and the extra LLM call cost. This gives a complete picture of what the tool does internally.

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?

Despite being detailed, every sentence adds value: purpose, mechanism, return format, refusal reasons, use cases, and cost trade-off. It is front-loaded with the core value proposition and maintains a logical flow 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?

The tool is complex, but the description covers routing, extraction, return values, refusal reasons, and comparative guidance with ask_pipeworx. With no output schema, the description successfully explains return values and error handling, making it self-sufficient for an agent.

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

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

The input schema already documents all 6 parameters as aliases for 'question' with 100% coverage. The description does not add parameter-specific details beyond implying the question is natural language routed through a tool-selection process, which is already clear from the schema. Baseline of 3 is appropriate.

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

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

The description clearly states this is a hallucination-resistant answer mode that extracts answers strictly from tool results, contrasting it with the sibling tool ask_pipeworx. It specifies the high-stakes use case and explicitly differentiates from casual 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?

It provides explicit guidance on when to use this tool (quoted/cited/acted-on answers, financial/legal/medical lookups) and when not to (casual lookups, preferring ask_pipeworx). It also names the exact alternative and highlights the extra LLM call cost.

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 is exceptionally transparent, disclosing many behaviors beyond the annotations: resolver contract (market_match_confidence, match_score, alternatives), parent_event extraction, news fallback mechanisms (_fallback_attempted, retry_after_sec), safety short-circuiting for low-confidence matches, handling of closed/dead markets, wide-spread market warnings, and resolution-rule risk details. This far exceeds the baseline set by 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 long but exceptionally well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every sentence carries substantive information. While it could be more concise, the complexity of the tool justifies the length, and the front-loaded purpose statement makes 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?

Given the tool's complexity (multiple fan-out sources, resolver behavior, parent events, news fallbacks, safety mechanisms), the description covers all relevant aspects comprehensively. It explains response shapes, edge cases, and precautions thoroughly. No output schema exists, so the description carries the full burden, and it does so exceptionally.

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 some context about how parameters affect behavior (e.g., fan-out examples and depth differences), but the schema descriptions already clearly explain each parameter. The description does not significantly enhance parameter understanding beyond what the schema provides.

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

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

The description clearly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It identifies the specific verb (research), resource (Polymarket bet), and input types (slug, URL, question text). It also differentiates itself from sibling tools by focusing on bet research and providing example queries like 'should I bet on X'.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', providing clear usage context. It doesn't explicitly state when not to use the tool or name alternative tools, but the intended use cases are well-defined.

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

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

Beyond the readOnly/idempotent annotations, the description reveals parallel execution, data sources (SEC EDGAR/XBRL, FAERS), correct handling of off-calendar fiscal years, sorting by primary metric, and return format with citation URIs. No contradiction with annotations.

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

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

While longer than most descriptions, every sentence delivers actionable information: trigger phrases, scope limits, data fields, fiscal year handling, sorting behavior, output content, and comparison to sequential lookups. The opening examples immediately convey the tool's purpose.

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

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

With no output schema, the description thoroughly covers return values (paired data + citation URIs), both entity types' data specifics, edge cases like fiscal year discrepancies, and the tool's advantage over sequential lookups. It provides sufficient detail for an agent to select and invoke the tool correctly.

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

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

Although schema coverage is 100%, the description adds substantial meaning by explaining what each type retrieves (10-K financials vs FAERS counts), how values are interpreted (tickers/CIKs vs drug names), and that results are sorted by primary metric. This goes far beyond the schema's basic documentation.

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 performs side-by-side comparison of 2-5 companies or drugs in a single parallel call, with multiple trigger query examples. It distinguishes from siblings by explicitly preferring it over sequential single-entity lookups and naming the alternatives.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists example user queries. It provides clear context for when to use company vs drug types and highlights the efficiency gain over sequential lookups.

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 description adds critical context: account requirement, depth 'thorough' paid plan, expected latency 15-60s, contradiction scanning for standard/thorough, semantic excerpting of large records, and guarantee that citations are always fetchable. 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 long but structured; it front-loads account requirement and core purpose, then details depth modes, alternatives, and return format. Every sentence conveys a distinct fact, though a few details (e.g., the citation URI explanation) could be tightened. For a tool with this many behavioral nuances, it is appropriately detailed.

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?

Description covers prerequisites, use cases, parameter options, return structure (findings packet with evidence, gaps[], contradictions[], hop fields, citation URIs), latency, and limitations. Even without an output schema, the description paints a complete picture of what to expect.

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

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

Schema coverage is 100%, so baseline 3. Description adds valuable semantics: explains depth enum with hop counts ('quick=3 (single hop), standard=5...thorough=8 paid'), notes 'thorough' requires paid plan, and describes gap-recovery behavior. Question parameter is self-explanatory, but description clarifies it accepts broad/multi-part questions.

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 defines the action: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' and explains how it decomposes questions into facets, routes to parallel tools, and returns findings. It distinguishes itself from siblings by explicitly contrasting with ask_pipeworx for single lookups and breaking news.

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

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

Explicitly states alternatives: 'If you are not signed in, use ask_pipeworx instead' and 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx'. Also gives best-use case: 'Best for broad/multi-part questions over structured data'.

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 readOnly and idempotent; the description adds behavioral context by explaining that results include full input schemas with curated examples and are 'ready to call directly, no second schema lookup needed.' This goes beyond the structured annotations and clarifies the output format, though it does not mention rate limits or error 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 reasonably concise but includes a lengthy enumeration of domains, which, while informative, could be trimmed. The most important information (find tools, when to use, return format) is front-loaded.

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

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

Despite lacking an output schema, the description covers the return format (names, descriptions, full input schemas), the limit parameter, and the call-first workflow, making it quite complete 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 description coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema; it restates that query is a natural language description and that aliases exist, but the schema already documents these. The only added context is the initial guidance to describe the data or task, which is minimal.

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

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

The description opens with 'Find tools by describing the data or task,' which clearly states the verb (find) and resource (tools). It then enumerates specific domains and explains the return value (top-N tools with schemas), effectively distinguishing it from siblings that answer specific queries.

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

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

The description provides explicit usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and instructs 'Call this FIRST when you have many tools available.' This clearly delineates when to use this meta-tool versus going directly to a domain-specific sibling.

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 readOnly/idempotent, but the description adds significant non-obvious behavior: parallel fan-out across five data sources, soft-failure for sunsetted USPTO PatentsView, GDELT→GNews fallback, filing count limit (up to 5), and zero-padded CIK requirement. These details tell the agent exactly what to expect at runtime.

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 front-loaded with illustrative examples and a clear purpose statement. It contains many details (return fields, sources, caveats), all relevant, but is somewhat long. Each sentence earns its place, though trimming could improve scannability.

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

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

With no output schema, the description thoroughly enumerates the exact return fields (CIK, filings, fundamentals, patents, news, LEI) and their sources/formats. It also covers input constraints, fallback behavior, and edge cases (patent sunset, name unsupported), making the tool fully actionable for an agent.

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

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

The input schema already covers both parameters with descriptions, and the description reinforces with concrete examples ('AAPL', '0000320193') and explains the zero-padding requirement. This adds useful nuance beyond merely repeating 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 opens with concrete examples and states a clear action: 'full cross-source profile of a US public company in ONE parallel call.' It explicitly differentiates itself from sibling tools by positioning as the preferred holistic lookups over chaining single-pack lookups and by pointing to resolve_entity for name-only inputs.

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

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

Provides explicit when-to-use guidance ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and clearly states the input constraint ('names not supported — use resolve_entity first if you only have a name'), naming the alternative tool.

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

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

Annotations already mark destructiveHint and idempotentHint; the description adds context by explaining the purpose (clearing sensitive data, cleaning stale context) and that it targets previously stored memories. No contradiction with annotations.

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

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

Three sentences, each with distinct value: purpose, usage triggers, and related tools. 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?

Given the tool's simplicity, the description covers purpose, usage, and relationships. It doesn't detail return values, but no output schema exists and the behavior is straightforward.

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 documentation covers 100% of the single parameter with 'Memory key to delete'. The description adds no additional syntax or constraints, but none are needed given the schema's clarity.

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

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

The description clearly states 'Delete a previously stored memory by key' – a specific verb, resource, and scope. It distinguishes from siblings by explicitly pairing with remember and recall, making its unique role obvious.

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

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

It provides explicit usage triggers: 'context is stale, the task is done, or you want to clear sensitive data'. Also says 'Pair with remember and recall', which routes the agent to complementary tools and implies appropriate context versus alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful behavioral detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and discloses the output artifact ('a single text blob ready to drop at site-root/llms.txt'). 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 four sentences, each adding value: purpose, process, output, and use cases. It is front-loaded with the core action. The use-case list is slightly expansive but still relevant and not wasteful.

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 2-parameter read-only tool with no output schema, the description covers what it does, how it works, what it returns, and why you'd use it. The output is clearly described ('a single text blob ready to drop at site-root/llms.txt'), and no critical information is missing for an agent to select and invoke it.

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

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

The input schema describes both parameters (url and max_links) with clear explanations, giving 100% schema coverage. The description adds no additional parameter-level semantics beyond mentioning 'key links'; it does not even reference max_links. 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 opens with a specific verb+resource: 'Generate a production-ready llms.txt file for any URL' and names the target AI crawlers (ChatGPT, Claude, Perplexity). This clearly distinguishes it from sibling tools like scan_competitor_ai_presence, which focus on auditing rather than generating.

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

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

The description lists concrete use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing...'), giving clear context for when to invoke. It does not explicitly mention exclusions or alternatives, but the scenarios cover the main applications.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful context beyond these by mentioning 'OpenDota keyless data' (no authentication needed) and enumerating the returned profile fields, providing behavioral transparency about data source and output contents.

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, front-loaded sentence that immediately states the purpose and key data fields. Every word earns its place; there is 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 simple, read-only lookup tool with one parameter and no output schema, the description sufficiently covers what the tool does, what data it returns, and that it requires no API key. The annotations cover safety and side-effect concerns, making the description complete for this context.

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

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

The schema already provides full coverage of the single parameter 'account_id' with a description ('Steam32 account ID'). The description reiterates that the tool works by account ID but adds little semantic value beyond what the schema already states, so the baseline of 3 applies.

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

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

The description clearly states the tool returns a Dota 2 player profile by account ID, listing specific fields (name, country, rank tier, leaderboard rank, win/loss totals). This distinguishes it from sibling tools like search_players, which implies searching rather than direct retrieval by ID.

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

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

The description implies usage when you have an account ID ('by account ID'), but does not explicitly state when to prefer this over alternatives like search_players or provide any exclusions. It offers clear context for the primary use case but lacks explicit comparative guidance.

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

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

Annotations already declare all safety hints (readOnly, openWorld, idempotent, non-destructive), so the description's additional context about OpenDota keyless data and scope to pro play adds value beyond the structured annotations. It does not detail behavior such as response ordering, pagination, or rate limits, but given annotation coverage, the added context is helpful but not rich.

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, front-loaded with a clear topic ('Dota 2 hero meta'), and each sentence serves a purpose: declaring the data content and noting the optional filter and data source. There is no redundant or extraneous wording.

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 only two optional parameters, no output schema, and robust annotations, the description adequately conveys the data scope (pro play), the kind of data returned (pick/win/ban counts, attributes, roles), and the keyless access. It does not mention time range or default limit, but for a simple read-only data tool, the description is sufficiently complete for an agent to select and invoke it.

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

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

The input schema covers both parameters (role and limit) with descriptions and examples, so schema coverage is 100%. The description echoes the role examples ('Carry', 'Support') and adds 'Initiator' but does not provide additional semantic detail beyond what the schema already offers. Baseline 3 is appropriate as the description does not materially enhance 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 provides per-hero pick/win/ban counts, primary attribute, attack type, and roles for Dota 2 pro play. While it lacks an explicit verb like 'get' or 'list', the resource and scope are immediately clear. It distinguishes from sibling tools like pro_matches (match data) and get_player (player data) by focusing on hero meta stats.

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

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

The description implies usage for retrieving Dota 2 hero meta statistics and explains the optional role filter with examples, giving some practical guidance. However, it does not explicitly state when to prefer this tool over alternatives (e.g., pro_matches for match-level data) or provide exclusion criteria, leaving usage boundary implicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the scope (caller's subscriptions) and the exact returned fields, but no additional behavioral caveats like pagination or rate limits. This is adequate but not exceptional.

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

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

Two sentences, front-loaded with purpose, then return fields, then usage guidance. Every sentence earns its place with zero redundancy.

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

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

Despite no output schema, the description lists all return fields explicitly. The tool is simple (one optional param), annotations cover safety, and the description covers both usage and returns, making it complete for the agent.

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

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

The single parameter include_inactive has a fully descriptive schema (100% coverage), so the description does not need to add parameter semantics. It slightly reinforces the 'active' default but adds no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'List' and the resource 'the caller's active subscriptions', then enumerates the returned fields. It distinguishes this from sibling tools like subscribe and unsubscribe by specifying its role in reviewing subscriptions before adding or finding an id to cancel.

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 provides two concrete use cases: reviewing what you're monitoring before adding more, and finding an id to cancel. It implies alternatives (subscribe for adding, unsubscribe for cancelling) but does not explicitly name or contrast them.

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 rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token lifecycle, that feedback is free and doesn't count against quota, and that the team reads digests daily. Annotations only provide readOnlyHint=false, so the prose adds valuable behavioral context not present in structured fields.

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

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

The description is long but front-loaded with purpose and usage triggers; the claim_token workflow and rate-limit info are relevant. Some sentences like 'Not sure? Pipeworx tool names are the ones this connection lists' add marginal value, so it is not maximally concise but earns its length through density of useful information.

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

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

The description covers the full workflow: when to use, what to include, the claim_token retrieval flow, and rate limits. With no output schema, it still explains what responses look like ('returns a claim_token', 'returns the status and...what changed'). It is complete for the tool's complexity.

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

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

The schema already provides 100% coverage for all parameters, but the description enriches semantics by explaining the claim_token round-trip ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and instructing users not to paste end-user prompts. This goes beyond what the schema describes, warranting a score above baseline.

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

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

The description clearly states the tool's function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes itself from sibling research/prediction tools and explicitly scopes to tools served by this Pipeworx connection, which differentiates it from other server feedback channels.

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

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

The description explicitly enumerates when to use the tool ('Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise)') and when not to use it ('if the tool came from a different MCP server... file it with that server instead'). It also instructs users not to paste end-user prompts, providing clear alternative 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses valuable behavioral details: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This covers data provenance, privacy, and cache behavior, adding significant context beyond what annotations provide.

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

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

The description is a bit longer than strictly necessary, but every sentence adds value: core function, use cases, and technical caveats. The numbered use cases improve scannability. It is well-structured and not wordy, though it could be trimmed slightly without losing essential meaning.

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

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

For a simple tool with no output schema and a single optional parameter, the description is complete. It explains what is returned, why it is useful, data privacy, and cache behavior. No significant 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?

The only parameter 'window' has full schema coverage (100%) with a descriptive enum ('24h (default) | 7d | 30d') and an explanation of shorter vs longer windows. The main description mentions the options but adds no new semantic detail beyond the schema, so it meets the baseline of 3.

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

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

The description clearly states the tool's function: 'What other AI agents are calling on Pipeworx right now' and lists the specific outputs (top tools, top packs, total call volume). It distinguishes itself from siblings by focusing on aggregate trend data rather than individual tool discovery or question answering.

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: 'Useful for: (1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice...' This gives clear when-to-use context. However, it does not mention alternatives or when not to use, so it falls short of a 5.

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

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

The description discloses numerous behavioral details beyond the readOnlyHint annotation: the scan covers ~200 markets, deviations >3pp trigger signals, Jaccard similarity ≥0.30 filters semantic pairs, placeholder slugs are filtered (with >20% placeholder fraction returning null), and the fill check prices against live CLOB depth. This is rich, non-contradictory context that helps the agent anticipate edge cases.

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

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

The description is long but densely packed with essential information and well-structured using labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It front-loads the primary usage ('Call with NO args...') immediately after the purpose. While every sentence earns its place, the length might be slightly overwhelming for a quick scan, but the clear formatting justifies a strong score.

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

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

Given the tool's complexity (two modes, filters, fill check) and the absence of an output schema, the description is remarkably complete. It outlines the response structure ('opportunities[]', 'partition_check{...}'), explains the fill-check logic, and gives both positive and negative criteria for action. No critical details are missing for an agent to use the tool correctly.

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

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

Even though schema coverage is 100%, the description significantly enhances parameter understanding: it provides concrete examples for both `event` (e.g., 'fed-decision-may-2026') and `topic` (e.g., 'Strait of Hormuz traffic returns to normal'), clarifies that full URLs are accepted for `event`, and explains the difference between single-event and cross-event scanning in a way the schema alone does not.

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 opening sentence states the exact purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This is a specific verb+resource+method that clearly distinguishes it from siblings like polymarket_edges (edge tracking) and polymarket_fill_risk (fill risk). The description also details the two modes (event/topic), reinforcing its unique scope.

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

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

Provides explicit when-to-use guidance: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also names an alternative tool ('For custom sizing use polymarket_fill_risk') and gives actionable trade advice ('realizable_edge_pp ≤ 0... do not trade 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?

Despite strong annotations (readOnlyHint=true, idempotentHint=true), the description adds substantial behavioral context beyond them: edge is computed net of slippage, Kelly fractions are halved and capped at 0.25, a 24h-move warning flags when the edge may already be priced in, results are cached for 1h at the KV level, and the diagnostic output explains why a segment might be empty. It also discloses the unreliability of Fed signals without paid data.

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

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

The description is extremely long and dense, with all-caps blocks and parenthetical asides. It is front-loaded with the main purpose, but it includes implementation and historical details (e.g., per-sport alpha values, 'Run 8' comparisons) that are not necessary for selecting or invoking the tool. While structured into segments, it would benefit from tighter, more hierarchical formatting.

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 compensates by fully documenting the response structure: by_segment{model_driven, structural_arbitrage, concentrated_longshot}, fed_candidates/fed_note, and _diagnostics{...}. It also lists the fields carried by each opportunity (edge_pp_net, kelly_fraction, market.liquidity, etc.) and explains why segments may be empty, making the tool's behavior predictable for a complex read-only operation.

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

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

The schema already covers all 9 parameters with detailed descriptions (100% coverage), so the baseline is 3. The description adds value by conceptually grouping the tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) and explaining their role in dropping unrealizable opportunities, which helps agents understand how to tune them in combination. It also clarifies the relationship between min_partition_leg_kelly and min_kelly.

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

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

The description opens with a specific verb+resource+outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further distinguishes itself from siblings by noting agents can 'discover opportunities without paging hundreds of markets,' contrasting with more targeted tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description clearly states the primary use case: 'Built for "what should I bet on today"' and explains when to use it (discovery over pagination). It also provides context around specific features (e.g., Fed bets excluded from ranking) and how knobs filter results. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of a 5.

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

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

The description enriches the annotations with essential behavioral details: history bounded by 60-day TTL, snapshots written only on cache-miss causing gaps, decay computed from daily closes not intraday. This clarifies data availability and interpretation beyond the read-only/idempotent hints.

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

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

The description is densely informative but well-structured with labeled sections (Args, RESPONSE, LIMITS). The opening sentence states the core purpose, and every sentence adds value—covering inputs, output structure, and data caveats. No filler or redundancy.

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

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

Despite having no output schema, the description thoroughly explains the response shape: tracked[], expired[] with fields like trend and lifespan_days, and snapshot_dates[]. It also covers data limitations. For a read-only telemetry tool with simple parameters, this is complete.

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

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

The schema maintains 100% coverage for both parameters (days and window). The description restates the defaults and adds the phrase 'snapshot family', but does not introduce genuinely new meaning beyond what the schema's descriptions already provide. 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 identifies the tool as an edge persistence/decay tracker built from daily snapshots, asking 'how long has this edge existed and is it shrinking?' This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on temporal edge dynamics rather than raw edge calculation or arbitrage detection.

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

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

The description provides implicit usage guidance via the example contrasting fresh vs. 3-week-old edges, signaling when to consult this tracker (before trading to assess edge persistence). It mentions being built from polymarket_edges snapshots, implying a companion relationship, but does not explicitly name exclusion or alternative tools. Good context but not explicit when-not-to-use.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the description doesn't need to repeat safety traits. Instead, it adds rich behavioral context: it walks the order book ladder, distinguishes top-of-book vs VWAP execution, computes slippage and fill probabilities, and explicitly warns that partial basket fills convert an arb into a directional position. This is the kind of behavioral disclosure that helps an agent anticipate tool 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 and front-loaded, but necessarily long due to the tool's dual-mode complexity. It uses clear structural markers (SINGLE-MARKET, BASKET) and bolded requirements. No sentence is wasted, but it could be trimmed slightly by removing redundant emphasis on partial-fill risk. Still an efficient description for such a complex tool.

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

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

With no output schema, the description takes on the responsibility of documenting return fields, which it does for both modes. It covers the primary use-case and failure mode (unhedged position). However, it doesn't cover error conditions, timeouts, or verdict threshold interpretation. Given the tool's complexity, it is good but not exhaustive.

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 already cover all four parameters at 100%, so the baseline is 3. The description adds value by clarifying the 'exactly one of market/event' requirement and the mode-dependent interpretation of size_usd and side, including the auto-default for basket mode. This exceeds what the schema fields individually state, so a 4 is warranted.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from sibling tools by framing itself as a pre-trade risk check for polymarket_arbitrage and polymarket_edges signals. The two modes (single-market and basket) are explicitly named, leaving no ambiguity about the tool's 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 explicitly states when to use it: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why, citing partial-fill risk and unhedged directional positions. However, it lacks an explicit when-not-to-use or alternative tool recommendation, so it doesn't fully earn a 5.

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

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

Annotations already mark this as readOnly/openWorld/idempotent, and the description goes far beyond them by detailing compatibility_warning triggers, temporal_alignment semantics, and skipped_cross_type/subtype counters. It even warns that the tool may indicate 'no arb exists' when bet shapes are non-equivalent. This is rich behavioral disclosure beyond structural hints.

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

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

The description is long but every sentence adds value: purpose, modes, response structure, safety fields, and real-world caveats. It is well-structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. No padding or tautology.

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

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

Despite lacking an output schema, the description fully covers what the agent needs: response contents, safety fields, temporal alignment, and common failure modes. It also addresses the complexity of cross-venue spread comparison and why many pre-mapped shortcuts may not yield tradeable spreads. This is more than sufficient for a 3-parameter tool.

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

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

With 100% schema coverage, the baseline is 3, but the description adds significant meaning: it explains how the 'topic' parameter auto-fetches events, how explicit ticker/slug overrides work, and how parameters interact in the two modes. It also provides example values for each parameter, making selection and invocation unambiguous.

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

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

The description opens with a specific verb+resource+scope: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparison, and further specifies two operational modes.

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 outlines TWO MODES ('topic' shortcuts vs explicit ticker/slug pairings) and when to use each. It also provides crucial usage caution: 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' This gives clear context and limitations, exceeding simple when-to-use guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds the useful context that this is OpenDota keyless data, indicating no API key is required, and notes recency. However, it doesn't disclose details like pagination, rate limits, or data freshness beyond 'recent'.

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 short sentences, front-loaded with the tool's purpose, and every word adds value. No filler or repetition of schema/annotations.

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 and no output schema, the description lists the return fields (teams, league, winner, score, duration) and data source, giving the agent sufficient context to invoke it. It lacks explicit mention of sorting or the default limit, but the schema covers limits.

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 only parameter, limit, is fully described in the schema with default and max values (100% schema coverage). The description adds no additional parameter semantics beyond what the schema provides, 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 identifies the resource as recent professional Dota 2 matches and lists included fields (teams, league, winner, score, duration), distinguishing it from sibling tools focused on players and heroes. However, it lacks an explicit verb like 'list' or 'fetch', making the action implicit.

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 no guidance on when to use this tool versus alternatives such as search_players or hero_stats. There is no mention of exclusions or preferred contexts, leaving the agent to infer usage from the resource name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by disclosing the scoping behavior ('Scoped to your identifier') and the dual behavior of listing keys when the key is omitted, which goes beyond annotations.

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

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

The description is concise, front-loaded with the primary action, and each sentence adds value: purpose, use cases, and scoping/relationships. 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 retrieval tool with no output schema, the description fully covers what it does, when to use it, how scoping works, and how it relates to remember and forget. Combined with strong annotations, 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% for the single 'key' parameter, and its description already states 'omit to list all keys.' The tool description reinforces this but adds no new parameter-specific semantics beyond what the schema provides. 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: 'Retrieve a value previously saved via remember, or list all saved keys.' It uses a specific verb and resource, and differentiates from sibling tools like remember and forget by explicitly naming them.

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

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

The description provides clear usage guidance: 'Use to look up context the agent stored earlier' with concrete examples. It also gives alternatives: 'Pair with remember to save, forget to delete,' making it easy to decide when to use this tool.

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

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

The annotations state readOnlyHint=true, but the description says 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a state-changing side effect. This directly contradicts the readOnly annotation, so the transparency score is 1.

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

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

The description is four sentences, each earning its place: purpose, returned payload, filtering, and side-effect/alternative access. It is front-loaded with the primary action and contains no redundant or vague phrasing.

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

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

Even without an output schema, the description covers what data each alert carries (source, citation_uri, raw payload), filtering behavior, mark_read side-effects, and an alternate HTTP endpoint. It is sufficiently complete for a read-only feed polling tool, aside from the readOnly contradiction.

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 meaningful value by giving an example type ('sec_8k'), clarifying the 'since' filter against event timestamps, and explaining the mark_read side-effect and its impact on subsequent calls, all beyond the schema text.

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

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

The description opens with 'Pull fired events from your subscription feed,' a specific verb+resource statement that clearly distinguishes it from sibling tools like list_subscriptions and recent_changes. It unambiguously states what the tool does and what it returns.

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

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

It provides clear guidance for polling ('Polls work fine') and notes an alternative HTTP access path for scripts/dashboards, giving context on when to use the tool. However, it does not explicitly exclude or name alternative tool scenarios, stopping 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?

Annotations already mark this as read-only and idempotent. The description adds valuable behavioral details: fans out to SEC EDGAR, GDELT→GNews fallback for rate limits/5xx, USPTO patents with a soft-fail due to API sunset, and returns structured changes[] with citation URIs. 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?

Though long, the description is front-loaded with query examples and every sentence provides unique value (sources, syntax, output, alternative). There is no wasteful repetition.

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

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

For a tool with no output schema, the description explains the return format (changes[], total_changes, citation URIs), covers data sources and fallback behavior, and notes limitations (patents soft-fail). This is complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds a minor recommendation ('Use "30d" or "1m" for typical monitoring') but does not significantly extend the parameter meaning already present 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 is a change feed for a company over a specified window, with many query examples. It explicitly distinguishes itself from entity_profile (static profile), making its scope 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?

Provides an explicit alternative: 'Use entity_profile instead when you want the static profile...' along with example queries and a note about 'typical monitoring' with '30d' or '1m'. This gives clear when-to-use and when-not-to-use guidance.

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

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

The description adds meaningful behavioral context beyond annotations: memory is scoped by the agent's identifier, and persistence varies by auth state (persistent for authenticated users, 24 hours for anonymous). This complements the annotations (idempotentHint=true, destructiveHint=false) without contradicting them.

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

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

The description is concise and well-structured. It opens with the primary purpose, then gives usage scenarios, storage details, and companion tools. Every sentence contributes value, and the total length is appropriate for the tool's complexity.

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

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

For a simple key-value store with two parameters, the description is complete. It covers what to store, when to use it, how it's scoped, persistence guarantees, and explains the relation to recall and forget. No output schema is needed for a save operation, and the description is sufficient for an agent to decide 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?

The input schema already covers both parameters with descriptive examples (100% coverage). The description adds the key insight that the key is scoped by the agent's identifier, which is valuable semantic context not present in the schema 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 clearly states the tool's purpose: save data for later reuse. It uses a specific verb (save) and resource (data the agent will need), and distinguishes itself from the siblings 'recall' and 'forget' by explicitly mentioning them as complementary operations.

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

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

Provides explicit when-to-use guidance: when you discover something worth carrying forward (ticker, address, preference, subject). It also tells the agent to pair it with 'recall' for retrieval and 'forget' for deletion, effectively explaining the workflow and when not to use it.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. The description adds valuable behavioral context: it cascades through multiple lookup endpoints, returns citation URIs, auto-disambiguates inputs, and specifies exact return fields per type. This goes well beyond the annotation hints and enriches the agent's understanding of side effects and output structure.

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

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

The description is information-dense yet well-structured: it opens with natural-language triggers, then defines supported types and outputs, and concludes with the efficiency note. Every sentence adds value; no redundancy or filler. It is appropriately sized for a tool with two parameter types.

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

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

With no output schema, the description fully explains return values for both entity types, including citation URIs and the input formats. It also addresses ambiguity resolution ('auto-disambiguated') and internal cascading. For a resolution tool of this complexity, this is complete enough for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra semantics by illustrating acceptable value formats for each type (ticker, CIK, or name for company; brand/generic for drug) and noting auto-disambiguation. This provides practical nuance beyond the schema's terse examples, but the schema already carries most of the parameter meaning.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical/official identifier, with specific examples ('ticker for…', 'CIK for…'). It differentiates from sibling tools by emphasizing this is the 'FIRST' step when an ID is needed and lists exact output types (ticker/CIK, RxCUI). The verb+resource combination is explicit and distinct.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', giving a clear trigger condition. It also explains that it replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly state when not to use it or name alternative tools, so it falls short of a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds process details—probing each entity, ranking scores, and returning a ranked list with confidence and signal density—which gives the agent a clear picture of behavior beyond the hints.

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

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

Three sentences, front-loaded with the core action, then the use case, then the output. Every sentence earns its place; no redundant phrasing.

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

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

The description explains the tool's purpose, process, use case, and output format (score, confidence, signal density). Since there is no output schema, this is important. It doesn't cover edge cases like model failures or rate limits, but given the annotations, it is sufficiently complete for invocation.

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

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

The schema already covers all four parameters with 100% description coverage, so the baseline is 3. The description adds minimal context, such as 'your brand + N competitors' implying the first entity is the subject, but this is also in the schema. No significant semantic enhancement.

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, probes each with ai_visibility_check, ranks by score, and identifies most/least recognized. It distinguishes from sibling ai_visibility_check by focusing on side-by-side comparison rather than single-entity checks.

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

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

It explicitly frames the tool for competitive AI-marketing audits and gives an example query ('does Claude know about us as well as our competitors?'). It implies single-entity checks should use ai_visibility_check, though it doesn't name alternatives explicitly, which is a minor gap.

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

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

The description goes well beyond the annotations by disclosing the fan-out architecture, partial failure handling, and the 5-30s first-measurement latency for bundlephobia. It also mentions the sources_failed field to indicate resilience. No contradiction with annotations.

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

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

The description is front-loaded with the purpose, then flows through usage, output, limitations, and error handling. Every sentence adds unique value; there is no redundancy or filler.

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

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

Without an output schema, the description enumerates the summary block fields, per-advisory detail, links, and alternative versions. It also covers ecosystem restrictions and graceful degradation, making the tool fully comprehensible for an agent.

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

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

The input schema already covers both parameters with descriptions, including scoped package acceptance and default version behavior, so the schema_description_coverage is 100%. The description adds the ecosystem scope but does not materially enhance per-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 identifies the tool as a composite npm package evaluation check, naming the specific external sources (deps.dev, bundlephobia) and the decision context. It is distinct from all sibling tools, which focus on other domains like AI presence or market research.

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

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

Explicit usage triggers are given ('is X safe / popular / small' or 'what does adding lodash cost me'). It also states which ecosystems are supported and directs non-npm queries to deps.dev:version, providing clear alternative 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 a safe, idempotent read operation. The description adds useful behavioral context: it mentions OpenDota is keyless (no authentication needed) and that results may be empty due to rate-limiting. This goes beyond the structured hints and clarifies the data source and a common failure mode.

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, front-loaded with the core purpose, and contains no filler. It efficiently conveys the action, target, return value, and an important caveat.

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?

Though there is no output schema, the description explicitly states what is returned (account IDs and similarity scores) and includes a rate-limit caveat. Given the tool's simplicity and the rich annotations, this is sufficient context for an 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?

The input schema has 100% description coverage for both parameters, so the baseline is 3. The description's mention of 'persona (display) name' largely echoes the schema's parameter description, and it does not add meaning to the 'limit' parameter. The description contributes minimal additional semantic 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 states a specific verb ('Search') and resource ('Dota 2 players by persona name'), and clearly distinguishes its function from siblings like get_player by focusing on search-by-name with similarity scores. It is concise 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?

The description implies usage (search when you need to find players by name) but does not explicitly compare to alternatives like get_player or state when not to use it. There is no mention of exclusions or alternate tools, so the guidance is only implicit.

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

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

Even with annotations declaring readOnly and idempotent behavior, the description adds substantial context: it reveals the return format (top-N passages with character offsets and similarity scores), the underlying mechanics (BGE-base-en embeddings, cosine over 500-char windows), and the 200K-char cap with truncation flagging. These details are not present in the structured data and meaningfully disclose behavior 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 four sentences but every sentence earns its place: action, use case, pairing, and technical limits. It is information-dense without being rambling, though the embedding details could be considered slightly niche for an agent selecting a tool. Overall, it is well-structured and 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?

The description fully covers the agent's needs: no output schema exists, but the description states the return shape (passages, offsets, scores). It also covers input constraints, the truncation behavior, and the integration with a sibling tool. For a tool of this complexity (3 parameters, no output schema), this is highly complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by framing the text parameter as 'text you already pulled' and giving concrete query examples ('supply-chain risk', 'fiscal year 2024 revenue'), which helps the agent understand expected input semantics beyond the plain schema descriptions. It does not add new parameter-level constraints, but enough to warrant 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 a specific verb+resource: 'Semantic search INSIDE a fetched record.' It distinguishes itself from sibling tools by emphasizing the 'inside' scope and by contrasting with whole-document grounding in ask_pipeworx_grounded. This makes its purpose unambiguous and differentiates it from related search/ask tools.

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

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

It explicitly says 'Use when the record is too big to cram into the prompt' and gives a clear pairing directive: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This provides strong when-to-use guidance and an alternative relationship, exceeding simple context.

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

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

Adds valuable behavioral context beyond annotations: OAuth requirement and non-persistence for anonymous/BYO, always-on feed with pull methods, SMS verification and daily cap, and return of the new subscription id. These details complement the readOnlyHint=false and idempotentHint=true annotations without contradiction.

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

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

The description is front-loaded with purpose and then systematically covers requirements, types, and delivery. It is dense but every sentence contributes; the webhook details are left to the schema, keeping the main description focused.

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

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

For a complex tool with nested params and no output schema, the description covers the return value, auth prerequisite, supported types, and delivery options. It does not cover error cases, but the schema already provides detailed parameter constraints and webhook auto-disable behavior, making the overall context fairly complete.

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

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

Schema coverage is 100%, but the description adds interpretive meaning beyond the schema, e.g., 'items:["5.02"] = officer change' and clarifies delivery constraints (verified phone, 10/day cap). This enhances understanding of the type-specific params.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream' — a specific verb and resource. It clearly differentiates from sibling tools like list_subscriptions and unsubscribe by focusing on creation and mentioning the returned subscription id.

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

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

Provides clear context: requires a Pipeworx OAuth account, and explains supported subscription types and delivery channels. It does not explicitly name alternative tools for listing or unsubscribing, but the usage context is evident from the action verb and prerequisites.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. Description adds substantive output context: returns category-bucketed example questions with exact tool+argument shape, drawn from a live catalog of thousands of tools. This clarifies what the agent can expect 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?

While longer than average, each sentence adds distinct value: query examples, output format, parameter behavior, and usage timing. Front-loaded with natural language triggers.

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 one-optional-param, no-output-schema tool, the description fully covers selection, invocation, and expected return structure. It even points to meta-tools to learn about, 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?

Schema covers 100% with topic description, and description reinforces it with concrete examples ('finance', 'pharma', 'betting') and behavior for omission ('Omit for a cross-category spread'), adding value beyond schema.

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

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

The description opens with concrete user phrasings ('What can I ask Pipeworx?', 'what can you do?') and identifies itself as 'the onboarding entry point for an agent that just connected', clearly distinguishing it from sibling tools like discover_tools by focusing on example questions with tool+argument shapes, not just tool listings.

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

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

Explicitly instructs: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.)' and provides guidance on no-args vs topic parameter.

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, the description discloses two important behaviors: ownership enforcement (you can only cancel your own subscriptions) and soft-delete semantics (row deactivated, historical events preserved). This aligns with destructiveHint=false and adds valuable non-obvious context.

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

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

Two sentences with no redundancy. The first sentence states the action; the second covers constraints and side effects. Every word 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 single-parameter tool, the description covers action, ownership constraint, and post-effect. It even references 'recent_alerts' for historical availability. This is sufficient for an agent to use it correctly.

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

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

Schema coverage is 100%, and the schema already describes the 'id' parameter as a subscription uuid returned by subscribe. The description adds minimal detail ('by id'), so 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 opens with 'Cancel a subscription by id', a specific verb and resource that clearly states the tool's function. This distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description provides clear context: ownership is enforced, and cancellation deactivates rather than deletes. While it doesn't explicitly name alternatives, the context makes the appropriate use case obvious.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, but the description adds substantial behavioral detail: how claims are verified (two distinct pipelines), the tolerance-based grading mechanism, and the return structure (verdict, actual value with pipeworx:// citation, reasoning). It also notes performance benefits (replaces 4-6 calls). No contradiction with annotations.

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

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

The description is longer than average, but every sentence serves a purpose: purpose, usage, routing, return value, and efficiency. It is front-loaded with the core function and examples. It could be slightly more concise, but the density is justified by the tool's complexity. No filler.

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

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

Given the tool has no output schema, the description sufficiently explains return values (verdict types, evidence citation, reasoning). It covers the two execution paths, tolerance behavior, and the type of claims it handles. All necessary context is present despite the absence of an output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning beyond the schema by explaining the tolerance_pct override behavior (e.g., setting 1-2 for hallucination detection) and how the claim routing works, which gives context for interpreting the 'claim' parameter. This raises it above baseline.

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

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

The description is very specific: it states the tool performs natural-language claim verification against authoritative sources, with example phrasings ('Is it true that…', 'fact check'). It clearly distinguishes itself from sibling tools by naming the two processing paths (SEC EDGAR/XBRL for company-financial claims, grounded pipeline for others) and noting it replaces 4-6 sequential calls, making it a distinct, high-level verification utility.

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: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides situational routing: company-financial claims use the structured fast path, all others fall through to the grounded pipeline. This gives clear context and differentiates it from sibling research/query tools like deep_research or ask_pipeworx.

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