Odds Api

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds key behavioral details: default model is free, _apiKey passed to Anthropic (BYO key, pay directly), return structure. No contradictions.

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

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

Two sentences, front-loaded with action and outcome. No waste. Well-structured and easy to parse.

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

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

Given 4 params, no output schema, but annotations present. Description explains return shapes (per-model score, confidence, signals, raw_response, combined view). Sufficient for agent to understand usage.

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

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

Schema coverage is 100% with descriptions. Description adds meaning by specifying default model, free usage, and that _apiKey is optional for Anthropic. Provides context beyond schema.

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

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

The description clearly states the tool's action: probe LLMs for entity knowledge and score visibility. It specifies the resource (business/brand/product/topic) and differentiates from siblings by focusing on AI visibility 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?

Explicitly states use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Discusses when to use _apiKey for Anthropic. No explicit when-not-to-use or alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it routes questions, fills arguments automatically, returns structured answers with stable citation URIs, works on every tier, and makes a single fast call. No contradiction with annotations.

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

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

Although long, the description is densely informative and front-loaded with the most important guidance ('PREFER OVER WEB SEARCH'). Every sentence contributes either usage criteria, scope, examples, or differentiation from sibling tools. No filler or repeated schema content.

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

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

For a single-parameter tool with no output schema, the description supplies sufficient context: what kinds of questions to ask, how the tool behaves, what the response includes, and when to consider alternatives. An agent has enough to select and invoke this tool correctly.

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

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

Schema coverage is 100% and includes six aliases for the question field, so the schema already documents parameters well. The description adds value by giving concrete example questions and clarifying that the input is a natural-language request, going slightly beyond the schema's minimal alias 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 states a clear purpose: it routes factual questions to the appropriate source among 5,721 tools and returns structured answers with pipeworx:// citation URIs. It explicitly differentiates itself from siblings like ask_pipeworx_grounded and deep_research, making the tool's 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?

The description gives explicit when-to-use guidance: prefer over web search for factual questions about real-world data, with example phrasings like 'what is', 'look up', and 'find'. It also states when to step up to ask_pipeworx_grounded or deep_research, and covers breaking-news usage.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the current experimental state: no candidate is active, it currently matches ask_pipeworx exactly, and it 'falls back to nothing.' This gives agents crucial runtime-behavior context that annotations cannot convey.

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

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

The description is front-loaded with the beta identity and core behavior, then covers current status, usage, and reassurance. It is mostly efficient, though phrases like 'currently matches ask_pipeworx exactly' and 'this IS a full working router' are slightly redundant.

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 natural-language router with rich annotations and full schema coverage, the description covers identity, current state, usage, and relationship to the stable sibling. It references the same response shape but doesn't detail it; given the reference to a known sibling, this is a minor gap rather than a blocking omission.

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

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

Schema coverage is 100%, with all aliases documented. The description adds only 'same arguments' as a reference to ask_pipeworx, which provides no additional parameter-level meaning. This is an appropriate baseline-3 case where the schema carries the semantic load.

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 and resource: this is the beta version of ask_pipeworx, an identical universal router over 5,721 tools with the same arguments and response shape. It clearly distinguishes itself from the stable ask_pipeworx sibling by emphasizing its experimental routing role.

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

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

It gives a clear usage condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also names the stable router as the comparison baseline and clarifies this is a full working router, not a stub. It lacks an explicit when-not-to-use instruction for stability-sensitive cases, so it misses the full 5.

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

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

Beyond the annotations declaring readOnly, openWorld, idempotent, and non-destructive, the description discloses the refusal mechanism with exact refusal_reason values, success and failure response shapes, evidence extraction from verbatim quotes, and the extra LLM call cost. This substantially exceeds what annotations alone convey and does not contradict 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 long but information-dense and front-loaded: purpose first, then mechanism, then return/refusal contract, then usage guidance and tradeoff. Every sentence contributes value, including the refusal-reason list, which compensates for the absent output schema.

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

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

Given the tool's complexity and lack of an output schema, the description is remarkably complete: it specifies routing behavior, success and refusal response structures, refusal categories, high-stakes use cases, examples, and cost-based comparison to the alternative. Nothing needed for correct invocation or interpretation is missing.

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

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

Schema description coverage is 100%, with all six parameters mapped to the same natural-language question and its aliases. The description does not add parameter-level detail, but the schema already documents the single meaningful parameter adequately, so the baseline score of 3 applies.

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

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

The description opens with a specific, differentiating verb phrase: 'Hallucination-resistant answer mode for high-stakes reads.' It then clarifies it routes like ask_pipeworx but extracts answers using only the tool result, making it clearly distinct from its sibling ask_pipeworx and ask_pipeworx_beta.

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 states when to use this tool: whenever an answer will be quoted, cited, or acted on, and when facts must not be invented, with concrete domains like financial verdicts and legal claims. It also names the alternative—ask_pipeworx—and the condition for preferring it, casual lookups, with a cost tradeoff.

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

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

The description extensively discloses behavioral traits beyond annotations. It covers response shapes (result.market, result.analysis, result.evidence), resolver contract (confidence, alternatives, suggestions), parent_event extractor, news fallback fields, safety features (low-confidence short-circuit, closed markets blocking), wide-spread warnings, and cancellation rule parsing. All these details align with readOnlyHint and destructiveHint false.

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

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

The description is extremely verbose and runs on with many details that could be structured in the output schema or separate documentation. While it is organized with section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.), the sheer length (over 200 words) makes it less concise than ideal. Several sentences provide highly specific edge-case information that may not be immediately relevant for initial tool selection.

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

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

Given the tool's complexity (multiple data sources, category fan-outs, various response fields, edge cases) and the absence of an output schema, the description is remarkably complete. It covers input variations, processing logic, response structure with all subfields, safety mechanisms (low-confidence, closed markets, wide spreads), and cancellation rules. An agent can fully understand the tool's behavior without external documentation.

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

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

Although schema coverage is 100%, the description adds significant value. For 'market', it explains accepted formats (slug, URL, question text). For 'depth', it clarifies that 'quick' uses 2-3 sources and 'thorough' uses full fan-out, with default 'thorough'. For 'include_raw', it details when to set true vs false and the size implications. These additions go beyond mere parameter names.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output goals (evidence packet, market-vs-model comparison). It also distinguishes from sibling tools by framing its usage for betting research, e.g., 'Use for "should I bet on X"'. This is specific and actionable.

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

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

The description explicitly provides usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also lists classifier categories and fan-out examples, helping the agent understand when this tool is appropriate. However, it does not explicitly state when not to use it or mention alternative tools for different use cases, which keeps it from a perfect 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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds significant behavioral context: it pulls data from SEC EDGAR/XBRL for companies (handling off-calendar fiscal years), and FAERS/FDA/trials for drugs, and sorts by primary metric. No contradictions with annotations.

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

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

The description is front-loaded with common trigger phrases and efficiently conveys key details. Every sentence provides useful information, though it could be slightly more concise without losing clarity.

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

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

Without an output schema, the description adequately describes return format (paired data + citation URIs). It covers input constraints, data sources, and sorting behavior, making it complete 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?

Schema coverage is 100%, baseline 3. The description adds meaning beyond schema by explaining what data each type pulls and the expected format for values (tickers/CIKs vs drug names). This adds value for correct usage.

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

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

The description explicitly lists trigger phrases (e.g., 'Compare X and Y', 'X vs Y', 'which is bigger') and states the tool performs side-by-side comparison of 2-5 companies or drugs. It clearly distinguishes from sibling tools like entity_profile, which provides single entity details.

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 advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear when-to-use guidance. However, it does not explicitly list alternative tools or when not to use it, though the context implies it.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive, and the description adds substantial behavioral context: findings packet shape, gaps[] and contradictions[], citation_uri resolvability, semantic excerpting, hop field, expected latency, and depth-tier behavior. 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 high-density and front-loaded with the most critical constraints (account requirement, alternatives, core scope). For a tool with this behavioral complexity, nearly every sentence adds distinct value, though a few points are restated (gaps, contradictions, ask_pipeworx routing).

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

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

Complete for a research tool with no output schema: covers prerequisites, scope, exclusions, alternatives, return-value structure, citation behavior, latency, and depth-mode differences. An agent has everything needed to decide whether and how to invoke it.

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

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

Schema covers 100% of parameters with detailed descriptions, including enum semantics for depth. The description adds context like 'decomposition is the point' and maps depth tiers to gap-recovery behavior, but largely reinforces rather than extends 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?

Describes a specific verb and resource: grounded multi-source research over 1497 structured data sources, decomposed into facets and routed in parallel. Explicitly distinguishes itself from open-web search and from ask_pipeworx, making its niche 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 explicit when-to-use guidance: broad/multi-part structured-data questions vs single lookups via ask_pipeworx vs breaking/current-news topics via ask_pipeworx. Also states the account/plan prerequisite and names a working alternative for unsigned-in users.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. Description adds that each result is ready to call directly with full schemas and curated examples, which is valuable beyond annotations. No contradictions.

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

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

Two focused sentences. First sentence states purpose with concrete examples. Second sentence explains return value and when to call. No redundant information, front-loaded with key action.

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

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

No output schema exists, but description adequately explains what is returned (names, descriptions, full schemas) and how to use. Agent has enough context to decide when to call and what to expect.

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

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

Schema coverage is 100% with descriptions for all parameters. Description adds meaning by clarifying that 'query' accepts natural language, listing aliases, and providing contextual examples (e.g., 'analyze housing market trends').

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

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

Description clearly states 'Find tools by describing the data or task' and lists specific use cases (SEC filings, financials, etc.). It specifies it returns top-N relevant tools with full schemas, distinguishing it from sibling tools that perform specific tasks.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set' and gives examples. It provides when-to-use guidance and implies not to use when the tool is already known.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent. Description adds behavioral context: fans out across multiple sources, details the asynchronous integration (sumset of PatentsView API, soft-fail behavior), and notes the unsupported name input, offering more than annotations alone.

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

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

Description is informative but slightly verbose, including examples and a list of return fields. It is well-structured and front-loaded with purpose, but could be trimmed without losing clarity.

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

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

Despite no output schema, the description thoroughly explains return values (cik, company_name, recent_filings with URIs, fundamentals, patents with sunset note, news, LEI). It covers limitations and input requirements, making it self-contained for an agent.

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

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

Schema covers both parameters (type, value) with descriptions. The description reinforces semantics by stating value accepts ticker or CIK, and type is only 'company', and adds context that names are not supported, slightly enriching beyond the schema.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call,' enumerating specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and returned fields. It distinguishes itself from sibling tools by advocating preference over chaining single-pack lookups.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also advises that names are not supported, directing users to use 'resolve_entity' if only a name is available, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true, so the description's 'Delete' adds little beyond that. It does not elaborate on permanence or side effects, leaving the annotations to carry the behavioral weight.

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

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

Two sentences, no fluff, front-loaded with the action and purpose. Every sentence contributes 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 one parameter, high schema coverage, and clear annotations, the description is sufficiently complete. It states purpose, usage context, and sibling relationships. No output schema, so return value explanation is not needed.

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

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

Schema coverage is 100% with a description for the 'key' parameter. The description adds only 'by key', which is redundant. It does not clarify format or constraints beyond what the schema provides. Baseline score of 3 is appropriate.

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

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

The description states 'Delete a previously stored memory by key', which clearly identifies the verb and resource. It mentions pairing with 'remember' and 'recall' but does not explicitly distinguish when to use this over those siblings. The purpose is clear but lacks direct sibling differentiation.

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

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

Explicitly describes when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with related tools, providing implicit context for alternatives. No explicit 'when not to use' statement, but the given guidance is specific and actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as false. The description adds behavioral details: it fetches the page, extracts title/description/key links, and outputs standard markdown. It could be more transparent about potential limitations (e.g., handling of large pages or dynamic content), but overall it's adequate.

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 states the tool's action, explains the process, and lists use cases in a single paragraph with no wasted words.

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

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

Despite no output schema, the description sufficiently explains the output ('single text blob ready to drop at site-root/llms.txt') and covers the process and use cases. No critical missing information.

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

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

Schema coverage is 100% with clear descriptions for both parameters (url and max_links). The description does not add new semantic information beyond the schema, mentioning only the default/max for max_links which is already in the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for any URL, explaining the process (fetches page, extracts title/description/key links, emits standard markdown). It distinguishes itself from all sibling tools, none of which relate to llms.txt generation.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for own project, auditing competitor. While it doesn't explicitly state when not to use or name alternatives, the context of sibling tools makes the unique purpose clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds value with 'Higher quota cost per call' and scope ('single event'). No contradictions.

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

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

Single front-loaded sentence with no wasted words. Efficient and to the point.

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 output schema present, return format is covered. Description provides core purpose and cost hint, but could elaborate on parameter usage or when to prefer over sibling tools.

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 only 20% (only 'markets' has description). Description adds context for 'markets' (player props, alt lines) but ignores other 4 parameters. Insufficient compensation for low coverage.

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

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

Description clearly states 'Odds for a single event', distinguishing it from 'get_events' and 'get_odds' by emphasizing richer markets like player props. Verb and resource are specific.

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

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

Implies use when richer markets needed via 'allows richer markets' and 'Higher quota cost per call', but lacks explicit when-not-to-use or differentiation from sibling 'get_odds'.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds context: returns upcoming+live events, no odds, and purpose for ID discovery. No contradictions.

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

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

Single sentence, front-loaded with key info, no filler. 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?

Given existence of output schema, description need not explain return values. However, with 3 undocumented parameters and no schema description, some gaps remain. Adequate for a simple tool but not fully 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 0%, so description must compensate but provides no parameter details. Purpose is clear but does not explain sport_key, event_ids, or date_format formats. Output schema exists but not referenced.

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

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

Description clearly specifies verb (get), resource (events for a league), and distinguishes from siblings like get_event_odds by stating 'without odds'. It also explains the utility (discover event IDs).

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

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

Description implicitly advises when to use (when event IDs needed without odds) by contrasting with odds-including tool. However, it does not explicitly state when not to use or name alternatives like get_event_odds.

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

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

Annotations declare read-only, idempotent, non-destructive behavior. Description adds the crucial behavioral detail of quota credit consumption, which is beyond annotations. No contradiction.

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

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

Two-sentence description: first sentence succinctly states purpose, second delivers critical usage constraint. No unnecessary words, highly efficient.

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

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

Covers core functionality and cost implications. With output schema present, return structure is documented. Could briefly mention required sport_key, but it's implied by 'in a league'.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by linking markets and regions to credit cost, aiding parameter selection. Each parameter is well-defined 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 retrieves current odds for upcoming and live events in a league, using a specific verb and resource. It distinguishes itself from sibling 'get_event_odds' which focuses on individual events.

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

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

Provides explicit guidance on quota credit cost per market/region, advising careful selection. Lacks explicit comparison to alternative tools or when-not-to-use conditions, but the cost note is practical.

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

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

The annotations already indicate this is a safe, read-only, idempotent operation, so the description's main contribution is the disclosure that each call costs 2 requests. This is a meaningful operational trait not captured in the annotations. The description adds this valuable context without contradicting 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 two short sentences that efficiently convey the core purpose and a key operational constraint. There is absolutely no filler or redundancy; 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?

Given the tool's simplicity, the presence of an output schema, and comprehensive annotations, the description covers the basic purpose and cost. However, it lacks usage guidance relative to sibling tools and leaves the sport_key parameter undocumented, creating a clear gap. It is minimally viable but not fully 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 description does not clarify any parameter semantics. The schema describes 'days_from' adequately, but 'sport_key' has no description and is required. The description does not compensate for this gap, leaving the agent to infer what values are valid for sport_key. With only 50% schema description coverage, the description should have provided additional parameter context but 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 description clearly identifies the resource as scores, specifically 'Live + recent final scores', which distinguishes it from sibling tools like get_odds or get_events. While it lacks an explicit verb, the title 'Get Scores' and context make the purpose unambiguous. It does not explicitly differentiate from siblings beyond the resource type, but the scope is clear.

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?

There is no guidance on when to use this tool versus alternatives such as get_odds or get_events. The only additional note is the cost ('Costs 2 requests per call'), which is an operational consideration but does not help the agent choose between tools. No exclusions or conditional usage are provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds the behavioral nuance of default in-season filtering, which is 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?

Single, concise sentence front-loading purpose and usage. Every word earns its place; no fluff.

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

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

With one parameter fully documented, annotations covering safety, and an output schema existing, the description provides all necessary context for correct invocation.

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

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

Schema description coverage is 100% and already explains the 'all' parameter with default false. The description largely restates this (default in-season) without adding new semantics.

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

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

Clearly states it lists sports/leagues with a specific verb (list) and resource (sports/leagues). Distinguishes from sibling tools like get_events or get_odds that deal with different data.

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

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

Explicitly says by default returns in-season and shows how to include out-of-season. Doesn't explicitly exclude alternatives but context from sibling names makes the tool's specific role clear.

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds value by listing the exact return fields and noting that only active subscriptions are returned by default. No contradictions with annotations.

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

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

The description is concise with two sentences: one stating the core function and return fields, the second giving a usage tip. No unnecessary words, well-structured.

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

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

The description provides return fields and usage context, which compensates for the lack of an output schema. For a simple read operation with one optional parameter, it is sufficiently 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 input schema has 100% description coverage for the single parameter 'include_inactive', so the schema already documents its meaning. The description does not add further semantic value 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 title and description clearly state that the tool lists the caller's active subscriptions. It specifies the verb 'List' and the resource 'subscriptions', and distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by focusing on listing.

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 this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke the tool, though it doesn't explicitly state when not to use it.

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

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

Annotations already convey read-only and non-destructive behavior. The description adds useful behavioral detail beyond annotations: it reads from The Odds API usage headers, reflects the key serving the call, and indicates real-time availability of related tools. 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?

Two sentences, concise and front-loaded with the most important information: what is measured and where it is read from. Every clause adds value and there is no redundancy or filler.

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

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

For a zero-parameter, read-only quota tool with an output schema and comprehensive annotations, the description covers what it returns (credits left/used, availability, plan size) and why it is useful. Nothing essential is missing.

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

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

The tool has zero parameters, so the schema fully covers parameter information. The description adds relevant context about the implicit 'key serving this call' and the data source, which is appropriate even though no explicit parameters exist.

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 names a specific resource (monthly request credits) and a clear action (reading usage headers), and it explains what the tool reports: credits left/used, current availability of odds/scores tools, and plan size. This clearly differentiates it from data-returning siblings like get_odds and get_scores.

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 makes the usage context clear: use it to check quota state and whether odds/scores tools can return data right now. It does not explicitly name alternatives or state when not to use it, but for a quota-checking helper the context is understandable without exclusions.

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

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

Goes far beyond the annotations by disclosing the claim_token workflow for tracking feedback, the daily digest review, rate limiting (5 per identifier per day), free usage, and quota exemption. This gives the agent critical behavioral context like the fact that filing without an account returns a token for later status checks.

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, every sentence earns its place by covering a distinct aspect: purpose, use cases, scope exclusion, token behavior, team process, rate limits, and cost. The structure is front-loaded with the core action and then flows logically from usage to mechanics, with no filler or repetition.

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

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

This is a feedback tool with 4 parameters, all optional, and no output schema. The description supplies the missing context: return behavior (claim_token), lifecycle (daily review, status checking), restrictions (rate limit, scope), and the necessary distinction between Pipeworx vs foreign tools. It is fully self-contained and agent-actionable.

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 meaningful semantics beyond the schema: it clarifies that claim_token should be used with no other arguments to read a previous report, instructs how to phrase the message ('in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), and defines the relationship between feedback types. This extra nuance justifies above baseline.

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

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

The description opens with a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately distinguishes from siblings by describing the feedback purpose and explicitly scoping to Pipeworx tools, leaving no ambiguity about what this tool does.

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 with concrete examples (bug, feature/data_gap, praise). It also gives a clear when-not-to-use exclusion ('if the tool came from a different MCP server... file it with that server instead') and even directs users to check the connection's tool list if unsure, making alternative handling explicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds specific behavioral traits: self-aggregating signal from CF analytics, no PII, caching policy (5min-1h depending on window). This exceeds what annotations provide.

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

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

Description is compact, front-loaded with primary function, then use cases, then technical details. Every sentence adds value with no redundancy.

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

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

For a read-only trending tool with one parameter and no output schema, the description is complete. It explains data source, privacy, caching, and the meaning of window sizes. No gaps given the low complexity.

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

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

Schema coverage is 100% with description for the only parameter 'window'. The description adds extra semantics outside the schema: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enriches understanding beyond enum labels.

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

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

Description clearly states the tool returns 'top tools, top packs, and total call volume' over configurable windows. It specifies the resource (Pipeworx trending data) and the action (retrieving), distinguishing it from sibling tools like discover_tools or ask_pipeworx.

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

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

Description explicitly lists three concrete use cases: discovering hot data sources, confirming canonical tools, and checking alignment with collective demand. While it doesn't explicitly say when not to use, the use cases are actionable and context-rich.

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

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

Discloses algorithmic details: Jaccard similarity threshold (0.30), placeholder filtering (20% threshold), fill check behavior, and response structure. No contradictions with annotations (readOnly, openWorld, idempotent). Adds significant context beyond annotations.

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

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

Well-structured with front-loaded purpose and clear mode separation. However, dense with technical thresholds (3pp, 0.30, 20%) which, while precise, might be streamlined for agent use. Still efficient for the complexity.

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

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

Despite no output schema, description fully explains response fields (opportunities[], partition_check, fill check details) and cross-references another tool. Covers all necessary behavior for selection and invocation.

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

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

Schema covers 100% of parameters. Description adds meaning: explains each parameter's mode, gives example values (e.g., 'fed-decision-may-2026'), and clarifies that event accepts full URLs. Compensates fully for any schema gaps.

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

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

Clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. Distinguishes between three modes (no args, event, topic) with specific explanations, differentiating from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly says when to call with no args for trending scan, event for a specific market, and topic for cross-event scanning. Provides recommendations and warns not to trade when realizable edge ≤ 0, and references polymarket_fill_risk for custom sizing.

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

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

Annotations set readOnlyHint=true, etc. The description adds substantial behavioral context: caching (1h KV), response structure (by_segment with diagnostics), tradeable-edge knobs, model families, and per-opportunity fields. No contradictions with annotations.

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

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

The description is well-structured with clear sections: opening purpose, model segments, knobs, response structure. It is front-loaded with the main purpose. However, it is somewhat verbose (over 600 words); could be more concise but the detail is valuable.

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

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

Given no output schema, the description thoroughly explains the return structure: top-level by_segment, per-opportunity fields, and diagnostics. It covers caching, edge calculation, and filters. For a complex tool with 9 parameters and multiple segments, the description is very complete.

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

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

Schema coverage is 100% with descriptions for all 9 parameters. The tool description adds extra context for some parameters (e.g., slippage_pp explains Polymarket fees, min_partition_leg_kelly explains its application), adding value beyond the schema.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the use case 'what should I bet on today' and distinguishes from sibling tools like polymarket_arbitrage by focusing on edge discovery without paging hundreds of markets.

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

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

The description explicitly says when to use: 'agents discover opportunities without paging hundreds of markets.' It details three segments and tradeable-edge knobs. It notes that Fed bets are excluded from ranking. However, it does not explicitly state when not to use this tool or provide direct comparisons with alternatives.

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

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

Annotations indicate safe read/idempotent operation. The description adds rich behavioral context: return structure (tracked, expired, snapshot_dates), time-series computation, limits (60-day TTL, start date), and decay methodology (daily closes, not intraday).

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 packed with value but somewhat lengthy. Information is front-loaded with the core question. Every section serves a purpose, but could be slightly trimmed for conciseness.

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

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

Despite no output schema, the description fully documents the return fields and their semantics, including edge_pp_net, first_seen, trend, decay_pp_per_day, expired objects with lifespan_days, and snapshot_dates. Also covers limits and assumptions comprehensively.

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

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

Schema coverage is 100% with basic descriptions. The description adds meaningful context: default values, valid ranges (days clamp 2-30, window family options), and explains how parameters affect the response (lookback, snapshot selection), going beyond the schema.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' with a specific question it answers, and distinguishes itself from sibling tools like polymarket_edges by focusing on historical tracking.

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

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

The description explains the use case ('how long has this edge existed and is it shrinking?') and contrasts fresh vs old edges, but does not explicitly state when not to use it or name specific alternatives beyond implicit differentiation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds critical context: walks the order-book ladder, returns slippage and fill details, and warns about partial basket fills converting arb into directional position. No contradictions.

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

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

The description is well-structured with clear section headings (SINGLE-MARKET, BASKET) and bullet-like formatting. It is somewhat verbose but each sentence adds value. Minor conciseness improvements possible, but overall effective.

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

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

Despite no output schema, the description lists all return fields for both modes, explains the meaning of verdict and profit_usd, and mentions key risks. Missing minor details like error handling or default behavior when neither market nor event is provided, but it's sufficiently complete for informed use.

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

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

Schema description coverage is 100% with good descriptions, but the tool description adds semantic nuance: clarifies size_usd interpretation for buys vs sells, default basket side logic, and the mutual exclusivity of market and event. Enhances understanding beyond raw schema.

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

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

The description clearly states the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' with explicit single-market and basket modes. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by being a pre-trade risk check.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overrun not capturable, partial fills lead to directional risk). Provides clear when-to-use and when-not-to.

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. The description adds substantial runtime transparency: safety fields, compatibility codes and their meanings, handling of unknown legs, skipped comparison counters, temporal alignment semantics, and the gross-vs-net fee caveat. This is far beyond what annotations provide and contains no contradiction.

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

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

The description is front-loaded with the core purpose and then organized into modes, response, safety fields, and caveats. It is long and somewhat repetitive around temporal-alignment explanations, but nearly every sentence carries substantive operational detail, so the length is mostly justified.

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 carries the full burden of explaining return values, and it does so comprehensively: leg-by-leg prices, spread fields, flags, warning codes, skipped categories, and fee treatment. It also warns about false confidence and tells the agent to read compatibility fields even when matched pairs exist. Nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context: it explains the topic mode's pre-mapped behavior, that explicit ticker/slug override the mapped side, that both modes run the same matcher, and it lists concrete examples. This goes beyond the schema descriptions.

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

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

The description clearly states that the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, and it distinguishes itself by naming both venues and the two operation modes. It lacks explicit differentiation from closely related siblings like polymarket_arbitrage, so it stops short of a perfect 5.

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

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

The description gives explicit when-to-use guidance by explaining the two modes, how to choose between topic shortcuts and explicit ticker/slug pairings, and when returned spreads are meaningful versus when compatibility warnings apply. It does not name sibling tools as alternatives, but the in-tool usage context is clear and actionable.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds scoping to identifier and listing behavior when key omitted, which adds value beyond annotations.

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

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

Three concise sentences, each with distinct purpose: operation, usage guidance, and contextual details. No redundant 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 read-only tool with one optional parameter and robust annotations, description covers purpose, usage, scoping, and sibling relationships. Missing return format details but not critical.

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

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

Schema coverage is 100% with clear description for the 'key' parameter. Description essentially restates the schema, adding no new semantic 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?

Clearly states the verb 'retrieve' and 'list', resource 'value' and 'saved keys', and distinguishes from siblings 'remember' and 'forget'.

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

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

Explicitly says 'Use to look up context the agent stored earlier... without re-deriving it from scratch', provides scoping info, and pairs with related tools. No explicit exclusion of alternatives but clear enough.

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

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

Annotation declares readOnlyHint=true, but description says mark_read:true flags events as read, which modifies state. This contradiction misleads about the tool's side effects.

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

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

Four sentences efficiently convey purpose, usage, and key parameters. Front-loaded with main function, 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?

Explains return fields, filter options, and side effect of mark_read. Mentions alternative endpoint. No output schema, but description compensates well.

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

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

Schema covers all parameters with descriptions. The description adds context on return fields and mark_read behavior, enhancing understanding beyond schema.

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

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

Clearly states it pulls fired events from subscription feed and returns recent alerts with specific fields. Does not explicitly distinguish from siblings like get_events, but the focus on subscription feed is implied.

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?

Explains when to use (for recent alerts), provides filter options, and mentions alternative endpoint. However, lacks explicit guidance on when not to use or comparison to 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 mark it as read-only, idempotent, and non-destructive. The description adds substantial behavioral detail: fans out to multiple sources (SEC, GDELT/GNews, USPTO), describes fallback logic, mentions API sunset, and outlines the return structure. No contradictions.

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

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

The description is well-structured with user query examples first, then behavioral details, then sibling differentiation. Every sentence adds value, though it could be slightly more concise given the detail. Still excellent.

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

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

No output schema exists, so the description fully compensates by stating the return format (changes[] grouped by source, total_changes count, citation URIs). It also addresses edge cases (fallback, sunset) and provides complete usage context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value beyond schema: explains since format with examples (ISO date and relative shorthand), clarifies value can be ticker or CIK, and notes type is limited to 'company'. This enriches understanding for proper invocation.

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

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

The description clearly states the tool's purpose: a change feed for a company in a specified window, with concrete examples of user queries. It distinguishes itself from the sibling tool entity_profile by specifying when to use that instead.

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

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

Explicitly provides when-to-use guidance, including alternative tool (entity_profile for static profile). Explains input formats for since parameter with examples and fallback behavior between GDELT and GNews.

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 context beyond annotations: key-value scoping by identifier, persistent memory for authenticated users, 24-hour retention for anonymous. No contradiction with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false).

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

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

Five tightly packed sentences, front-loaded with purpose, no filler words. Each sentence earns its place.

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

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

Given the tool's simplicity (2 required params, no output schema), the description completely covers purpose, usage, pairing, retention, and scope.

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

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

Schema coverage is 100% with descriptions, but the description adds concrete examples for keys (e.g., 'subject_property', 'target_ticker'), enhancing usability beyond the schema alone.

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

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

The description uses a specific verb ('save') and resource ('data the agent will need to reuse later'), clearly distinguishing it from related tools like 'recall' and 'forget' by mentioning pairing.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and provides alternatives ('Pair with recall to retrieve later, forget to delete'). Also clarifies persistence differences for authenticated vs. anonymous users.

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, idempotent, and non-destructive. The description adds substantial behavioral detail: graceful degradation of LEI/FIGI enrichment, ambiguous matches returning `figi_candidates`, explicit `unresolved` fields, source labeling, and internal cascading through multiple lookup endpoints.

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 trigger phrases and a clear directive. It is long and dense, but nearly every sentence carries substantive guidance; the length is justified by the complexity of the tool's multi-source resolution behavior.

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

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

Despite having no output schema, the description explains key return behaviors: `figi_candidates` for ambiguous matches, `unresolved` for failed identifiers, source labels, and drug RxCUI citations. Input handling, edge cases, and failure modes are covered well enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, but the description adds critical parameter semantics beyond the schema: pass only the entity name, bond issuers must be exactly as printed, and trailing security-class words will fail the FIGI lookup. The `value` parameter is given rich real-world usage guidance.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers needed by other tools, with specific verbs and examples. It distinguishes itself from siblings by naming the identifier types it returns and the entity types it supports.

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 clear when-to-use guidance. It does not explicitly name alternatives or when-not-to-use cases, but the context makes the usage boundary apparent.

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

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

Description explains it probes each entity with ai_visibility_check and returns ranked list with metrics. Annotations already declare readOnly, idempotent, non-destructive; description adds internal mechanism and output structure 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?

Three sentences: first defines core action, second explains mechanism, third provides use case and output summary. No wasted words, front-loaded.

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

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

Given no output schema, description adequately outlines output elements (ranked list with score, confidence, signal density). Could mention pagination or limits but sufficient for selection.

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

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

Schema coverage is 100%, but description adds key context: first entity treated as subject, default model is workers-ai, and context parameter for disambiguation.

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

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

Clearly states it compares AI visibility across multiple entities side-by-side. Verb and resource specific, distinguishes from sibling 'ai_visibility_check' which likely handles single entities.

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

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

Explicitly provides use case for competitive AI-marketing audits with example. Context of comparing multiple entities is clear, though no explicit when-not-to-use guidance.

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

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

Beyond annotations, describes graceful degradation on partial failures, timing details for bundlephobia's first measurement (5-30s), and mentions that failed sources will be listed in sources_failed. This exceeds annotation-provided 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?

Description is somewhat long but efficiently packed with information: purpose, usage, return format, and edge cases. Could be broken into shorter sentences, but very informative.

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

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

Given no output schema, the description thoroughly enumerates return fields (summary block, per-advisory detail, links, alternatives). Covers scope, behavior, and failure modes completely.

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

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

Schema coverage is 100%, but description adds value by clarifying that scoped packages are accepted and that version defaults to the latest published version. This is beyond 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 it is a composite check for npm packages, listing specific aspects (license, advisories, version history, bundle info). It distinguishes itself from sibling tools by focusing on npm dependencies and mentions that other ecosystems use a different tool directly.

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

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

Explicitly provides when to use: 'whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also notes NPM-only in v1 and points to alternatives for other ecosystems.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description goes beyond by detailing the embedding model (BGE-base-en), windowing strategy (500-char overlapping windows), character cap (200K chars with truncation and flagging), and the presence of character offsets for verification. No contradictions.

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

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

Three concise sentences that front-load the core purpose and then add key details. No unnecessary words or repetition. Every sentence adds value.

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

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

Given the tool's moderate complexity (3 parameters, annotations, no output schema), the description covers usage context, algorithm details, constraints, and integration with sibling tools. It is sufficiently complete for an agent to select and invoke correctly.

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

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

Parameter schema coverage is 100%, so the description does not need to add much. It provides example queries and explains the purpose of text (e.g., SEC 10-K body), but the schema already describes each parameter sufficiently. Therefore, baseline score of 3 is appropriate.

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

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

The description clearly states the action (semantic search inside a fetched record), the input (text and natural-language query), and the output (top-N passages with offsets and similarity). It distinguishes itself from siblings like ask_pipeworx_grounded by focusing on searching within a single record rather than grounding over multiple passages.

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

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

Explicitly advises use when the record is too large for the prompt, saving context and returning only relevant passages. It also mentions pairing with ask_pipeworx_grounded for grounding, providing clear guidance on when to use this tool versus alternatives.

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

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

Annotations already indicate idempotent and non-destructive. Description adds valuable context: OAuth requirement, SMS cap of 10/day, phone verification, webhook auto-disable after 10 failures, and HMAC signing details. This exceeds what annotations provide.

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

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

Information-dense but well-structured: purpose first, then requirements, types, delivery. Each sentence contributes essential detail. Slightly long, but front-loaded with core purpose. 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?

Thoroughly covers all aspects: account requirement, type-specific params with examples, delivery channels with constraints and behavior (e.g., webhook auto-disable, HMAC signing). No output schema, but the return value (subscription id) is mentioned. Very complete for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds significant value with concrete examples for each type's params and detailed delivery channel options, including constraints and signing mechanics. The schema descriptions are present, but the description enriches them.

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

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

Clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. Distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation.

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

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

Explicitly requires a Pipeworx OAuth account and explains why anonymous/BYO cannot persist subscriptions. Lists supported types and delivery channels. Could be improved by contrasting when to use this versus listing or unsubscribing, but the guidance is clear enough.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns example questions with exact tool+argument shape, and explains behavior with no arguments vs. passing a topic. No contradictions.

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

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

Description is well-structured, starting with example user queries, then explaining output and usage. It is slightly long but each sentence adds value; could be tightened slightly.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, parameter behavior, usage context, and output content. It fully addresses what an agent needs 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% for the single optional parameter. The description adds context beyond schema by explaining that omitting topic gives a cross-category spread, and provides examples of valid values.

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

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

The description clearly states the tool is 'the onboarding entry point for an agent that just connected' and explains it returns category-bucketed example questions with tool recommendations. It distinguishes itself from siblings like ask_pipeworx by mentioning meta-tools explicitly.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This provides clear when-to-use guidance, though it lacks explicit when-not-to-use or direct comparisons to alternatives.

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

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

Discloses ownership enforcement and deactivation (not deletion) with historical availability. Adds value beyond annotations (readOnlyHint=false, destructiveHint=false) by explaining the row state.

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

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

Two concise sentences, front-loaded with verb and resource. Every sentence adds value without redundancy.

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

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

Complete for a simple tool with full schema coverage and annotations. Explains all necessary behavioral and contextual aspects.

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

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

Schema covers 100% of parameters with description. The description adds no additional parameter semantics beyond what 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?

Clearly states verb 'Cancel' and resource 'subscription by id'. Distinguishes from siblings like 'subscribe' and 'list_subscriptions' by indicating cancellation and ownership enforcement.

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

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

States ownership constraint and deactivation behavior. Provides context but does not explicitly list alternatives or when-not-to-use. However, the purpose is straightforward.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds crucial behavioral nuance: could_not_verify means the check did not happen and must not be treated as evidence, unsupported means no source covers the claim, and the tool returns a specific verdict set with citation and reasoning. No contradictions with annotations.

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

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

The description is front-loaded with question-phrase triggers and a clear 'Use whenever' directive. Although longer than typical, each sentence adds value—routing logic, verdict meanings, error semantics, and efficiency benefit—and it is well-structured with 'IMPORTANT for callers' signaling.

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 covers return behavior: verdict values, the grounded/structured actual value with citation, and reasoning. It also explains error semantics (could_not_verify) and coverage semantics (unsupported), making it complete for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100% but the description adds meaning beyond bare field types: tolerance_pct overrides claim-wording tolerance, with practical values (1–2 for hallucination detection) and a default cap of 5. It also gives concrete examples for the claim parameter, making invocation clearer.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources, with specific verb 'validate' and resource 'claim'. It distinguishes from siblings by describing the company-financial SEC EDGAR fast path and grounded pipeline for other facts, and by noting it replaces sequential lookup calls.

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

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

Provides explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the fast-path vs grounded routing and that it replaces 4–6 sequential calls, but it does not name specific alternative tools or state when not to use this tool in favor of a sibling.

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