Iso

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

Annotations already declare idempotency and non-destructiveness. The description adds behavioral details: default model is free, Anthropic calls require a user-provided key and direct payment, return structure includes per-model fields and combined view. No contradictions with annotations.

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

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

Three sentences, ~70 words. Purpose first, then key details, then use cases. Every sentence is informative; no redundant or vague language.

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 4 parameters and no output schema, the description covers all needed aspects: what the tool does, how to configure models and API key, return structure, and typical use cases. It is complete for an AI agent to decide when and how to invoke.

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%. The description adds context: clarifies relationship between 'models' and '_apiKey' (API key only needed for Anthropic), explains default model, and notes 'context' helps with disambiguation. This adds value beyond the schema descriptions.

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

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

The description clearly states the action ('probe LLMs'), resource ('what they know about entity'), and output ('score visibility 0-100 per model'). It distinguishes itself from sibling tools like 'scan_competitor_ai_presence' and 'compare_entities' by focusing on visibility scoring across multiple models.

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 use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It provides context on default vs paid models (BYO key). While it doesn't explicitly state when NOT to use, the listed use cases provide sufficient guidance.

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

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

Annotations already declare read-only, open-world, idempotent behavior. The description adds meaningful behavioral context: it is a routing layer that fills arguments automatically, spans 5,743 tools and 1500 verified sources, and returns citations via stable pipeworx:// URIs. This goes beyond what annotations alone convey, with 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 longer than average but logically organized: scope, behavior, trigger phrases, examples, and a final routing instruction. It is not wasteful overall, though the emphatic capitalization and the slightly awkward final caveat keep it from being a 5.

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

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

Even without an output schema, the description fully covers what the tool accepts, what it returns, when to use it, and how it behaves internally. An agent has enough information to select this tool and invoke it with a suitable natural-language question.

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 useful parameter-level guidance: the input is a plain natural-language question, the tool fills arguments itself, and the many domain examples clarify what kinds of questions are appropriate.

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

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

The description clearly identifies a specific function: routing natural-language questions to the right tool and returning structured answers with stable pipeworx:// citation URIs. It gives concrete domains and examples, but it does not explicitly distinguish ask_pipeworx from the sibling variants ask_pipeworx_beta and ask_pipeworx_grounded.

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

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

The description explicitly says to prefer this tool over web search, lists triggering phrasings such as 'what is', 'look up', 'find', and 'get the latest', and even says to use it even when web search could also answer. It also provides a clear exclusion: unless the agent is porting analysis from another framework and already knows a specific tool.

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

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

Beyond the annotations, the description reveals important behavior: candidate routing improvements are enabled live when under test, no candidate is active right now, and there is no fallback — it is a full working router. This adds meaningful context about the tool's experimental nature and current state 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 front-loaded with the core definition and then provides current-state and usage guidance. Each sentence contributes useful context, though the wording around 'Falls back to nothing' is slightly ambiguous and could be tightened. Overall it is appropriately sized for a beta router with dynamic 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?

The description covers what the tool is, how it differs from the stable version, its current active state, and how to use it. Since there is no output schema, mentioning 'same response shape' as ask_pipeworx helps, though it does not spell out the actual response format. The reference to ask_pipeworx provides enough context for an agent to invoke it correctly.

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

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

Schema coverage is 100%, and all parameters are documented as aliases for the question field. The description adds no parameter-level details beyond saying 'same arguments' as ask_pipeworx, so it neither improves nor harms the schema-provided semantics. Baseline 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same 5,743 tools, arguments, and response shape. It distinguishes the tool from the stable ask_pipeworx by emphasizing its experimental routing edge, though it does not explicitly contrast it with ask_pipeworx_grounded.

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

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

The description explicitly says to use it exactly like ask_pipeworx when wanting the newest routing, and explains that results are compared against the stable router. It also notes that no candidate is currently active, so it currently matches ask_pipeworx exactly. It gives practical usage context but does not state clear exclusions or when to prefer ask_pipeworx_grounded.

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

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

Beyond the readOnly/idempotent annotations, the description discloses grounding behavior, exact success and refusal return shapes, the refusal_reason enum, and the extra LLM call cost. It clearly states that the tool refuses when the data does not directly answer, which is critical for high-stakes use. 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 dense but well structured: purpose, routing mechanism, return contract, refusal contract, use cases, and cost tradeoff. Every sentence carries decision-relevant information, and the most important aspect — hallucination resistance — is front-loaded.

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

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

With no output schema, the description fully explains what the tool returns: the success shape with evidence, confidence, source, and fetched_at, plus the refusal shape with concrete refusal_reason values. It also covers routing scope, aliases, and when to choose the sibling tool, leaving no essential gap for correct invocation.

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

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

Schema coverage is 100%, and the single semantic parameter (question) is fully documented in the schema, including alias fields. The description adds little beyond restating that natural-language questions and aliases are accepted, so the baseline 3 applies.

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

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

The description states a specific resource and behavior: a hallucination-resistant answer mode that routes through many tools, fetches data, and extracts answers only from tool results. It also distinguishes itself from the sibling ask_pipeworx by emphasizing grounded extraction, evidence, and refusal behavior.

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

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

It gives explicit when-to-use guidance: answers that will be quoted, cited, or acted on, plus high-stakes domains like financial verdicts, legal claims, and medical lookups. It also says when not to use it — casual lookups — and names the preferred alternative, ask_pipeworx, along with the 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds substantial behavioral context: resolution and classification process, fan-out behavior, response shapes (market, analysis, evidence), special cases (low-confidence, closed markets, wide spreads, cancellation rules), and safety mechanisms. 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 very long but well-structured with section headers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.). It is front-loaded with the core purpose. However, it could be more concise; some details (e.g., extensive resolver contract description) are verbose and could be simplified.

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 classification types, fan-out patterns, response shapes, edge cases), the description is remarkably complete. It covers resolution confidence, closed markets, wide spreads, cancellation rules, news fallback, and safety mechanisms. No output schema exists, but description explains response shapes thoroughly.

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

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

Schema coverage is 100% with all three parameters described. The description enhances understanding by providing examples for the market parameter, clarifying the depth parameter's meaning, and explaining the include_raw parameter's impact on response size. This adds value beyond the schema.

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

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

The description clearly states 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 (evidence packet + comparison). The use cases are explicitly listed, and the tool is distinguished from siblings like polymarket_arbitrage.

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

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

The description provides explicit contexts for use: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.' It includes fan-out examples for different bet types. However, it does not explicitly state when not to use this tool or name alternative tools, though siblings cover other aspects.

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?

Going beyond annotations (readOnlyHint, idempotentHint, etc.), the description reveals specifics: pulls latest 10-K from SEC EDGAR/XBRL for companies, handles off-calendar fiscal years, pulls FAERS data for drugs, sorts by primary metric, and returns citation URIs. No contradiction with annotations.

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

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

Description is front-loaded with common usage phrases and is appropriately detailed. At 4-5 sentences, it is efficient but could be slightly more concise without losing information.

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

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

For a tool with 2 parameters and no output schema, the description fully covers usage, parameter details, behavioral nuances, and return characteristics. No gaps identified.

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

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

Schema coverage is 100% with descriptions. Description adds meaning by explaining the data each type pulls (e.g., 'company pulls latest 10-K revenue...') and that values are tickers/CIKs or drug names with limits, enriching 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?

Description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with specific verb phrases like 'Compare X and Y' and 'head to head'. It explicitly distinguishes itself from sequential 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?

The description provides strong guidance to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', effectively telling when to use. It lacks explicit exclusions or listing of alternatives, but the context is clear.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's safe and non-mutating. The description adds further context by calling it a 'static' resolver and a 'curated catalogue,' confirming it is a read-only lookup without side effects. It also mentions the output fields ('ISO number, family and summary'), which goes beyond annotations.

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

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

The description is only two sentences, front-loaded with the core purpose and examples. Every sentence adds value, and there is no unnecessary repetition or filler. It efficiently conveys the tool's role and relationship to siblings.

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

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

Given the tool's simplicity (one optional parameter, no output schema, and strong annotations), the description covers everything needed: what it does, what it returns, and how it relates to a sibling tool. It is complete for an AI agent to understand and use correctly.

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

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

The input schema already describes the single optional parameter 'query' with its purpose and provides an example. With 100% schema coverage, the description does not add new parameter-level details beyond the schema. It mentions how to pass a number to get_standard, but that is usage guidance rather than parameter 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?

The description clearly states it is a 'curated catalogue of compliance-relevant ISO standards' with specific examples (ISMS/27000, privacy, etc.) and the output mapping (ISO number, family, summary). It also distinguishes itself as a 'static name→number resolver' and directs users to 'get_standard' for live records, which differentiates it from sibling tools like 'search_standards' and 'get_standard'.

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

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

The description explicitly tells when to use this tool: as a 'static name→number resolver' and to 'pass a number to get_standard for the live record.' This provides clear context for choosing between compliance_catalog and get_standard, though it does not explicitly mention when not to use it or alternatives for broader searches.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already establish the safety profile, and the description goes far beyond them: authentication requirement, 15-90s latency expectations, the never-invented guarantee with explicit gaps[], citations guaranteed fetchable (citation_uri present only when the source emits a resolvable one), semantic excerpting rather than head-truncation, and depth-dependent behaviors (gap recovery, contradictions[] scan, lead chasing). No statement contradicts the annotations.

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

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

The description is long (~3,900 chars) but nearly every sentence earns its place for a tool with three depth levels, auth gating, and no output schema. It is front-loaded with the most decision-critical facts (account required, use ask_pipeworx if not signed in, NOT open-web search). It loses a point for being one unbroken block of text with interleaved topics (the hop field appears mid-stream, and depth behavior is split across two separated passages).

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 full burden for return values — and it delivers: findings packet contents (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[], contradictions[], hop field, citation_uri resolvability, latency, auth, and sibling routing. Nothing an agent needs to correctly select and invoke this tool 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% for both params, so the baseline is 3. The description adds meaning beyond the enum labels: it ties each depth to concrete behavior ('standard' re-angles unanswered gaps, 'thorough' chases leads so multi-step questions resolve in one call) and adds latency per depth. It partially repeats schema content (gap recovery, contradictions[]), which keeps it from a 5.

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 verb+resource: 'Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources... in ONE call.' It explicitly differentiates itself from siblings — 'this is NOT open-web search' and 'For a single lookup use ask_pipeworx' — so an agent can distinguish it from ask_pipeworx and the other siblings without inspecting schemas.

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, when-not-to-use, and named alternatives: 'If you are not signed in, use ask_pipeworx instead — it works on every tier,' 'For a single lookup use ask_pipeworx,' and 'Best for broad/multi-part questions over structured data.' It also states the auth prerequisite (free account required, thorough needs a paid plan), leaving no ambiguity about eligibility.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by describing return format ('top-N most relevant tools with names, descriptions, and full input schemas') and noting that results are 'ready to call directly'. 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 purpose and includes a list of domains and usage guidance. While somewhat long, every sentence is relevant and structured logically. Could be slightly more concise but no wasted words.

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

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

Given the tool's role as a discovery tool, the description fully covers input (natural language query), output (top-N tools with schemas), and usage context (call first when unsure). No output schema exists, but the description compensates by explaining what is returned.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions that query accepts natural language and lists aliases, but the schema already provides identical information. The description adds no meaning beyond the schema.

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

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

The description clearly states the tool finds tools by describing data or task, listing many example domains. It distinguishes itself from siblings by being a meta-discovery tool, as seen in the explicit instruction 'Call this FIRST when you have many tools available'.

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

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

The description provides explicit usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)'. This clearly differentiates when to use this tool versus directly using a specific tool.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations. It discloses the full fan-out across sources, the meaning of sources_used/sources_failed, soft-fail behavior for patents, expected empty sections as real 'no data', resolved:false behavior for private companies, and fallback logic for news. This is rich, accurate behavioral context.

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

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

The description is long but densely informative; nearly every clause earns its place by explaining input variants, output fields, source behavior, or failure semantics. It is front-loaded with user-intent examples and the key preference rule. It could be improved with structured bullets or clearer section breaks, but there is no filler.

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

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

Despite having no output schema, the description fully explains what the tool returns: CIK, company_name, resolved_from/to, recent_filings with URIs, key fundamentals, per-source data, and sources_used/sources_failed. It also clarifies input resolution, private-company behavior, and type/value interchangeability, so an agent has everything needed 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%, so the baseline is 3. The schema already documents that type accepts company/ticker interchangeably and that value can be a ticker, CIK, or company name. The description reinforces this with concrete examples like 'AAPL', '0000320193', and 'Moderna', but does not add significant semantic meaning beyond the schema.

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

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

The description clearly identifies the tool's purpose: producing a full cross-source profile of a US public company in one call. It uses specific verbs ('profile', 'brief me', 'research') and a specific resource type, and it distinguishes itself from chained single-purpose lookups, making it unambiguous even among sibling tools.

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

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

The description gives explicit guidance: ALWAYS PREFER this over chaining single-pack lookups when the user wants a holistic view. It also explains what happens for private companies and what input forms are accepted. However, it does not explicitly name sibling alternatives like compare_entities or resolve_entity or state when those should be preferred instead.

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

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

The description confirms the destructive nature ('Delete') and adds context about clearing sensitive data, which complements the annotations (destructiveHint=true). However, it does not disclose potential side effects like cascade deletions or reversibility, but annotations already cover the destructiveness, so the description adds moderate value.

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

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

The description is two sentences with no wasted words. The action is front-loaded, followed by usage guidance and sibling references. Every sentence earns its place.

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

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

For a simple tool with one parameter, no output schema, and annotations covering destructiveness, the description is complete. It covers purpose, usage context, and relation to siblings, leaving no critical gaps.

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

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

Schema coverage is 100%, with the schema already describing the 'key' property as 'Memory key to delete'. The description only mentions 'by key', adding no extra meaning beyond the schema. Baseline 3 is appropriate as the description does not need to compensate.

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 deletes a memory by key, using a specific verb and resource. It distinguishes from siblings 'remember' and 'recall' by indicating deletion, and provides concrete usage scenarios (stale context, task done, clear sensitive data).

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

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

The description gives explicit when-to-use conditions ('context is stale, the task is done, clear sensitive data') and suggests pairing with related tools, but does not explicitly state when not to use or compare with alternatives beyond implying 'remember' and 'recall' are for storage and retrieval.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds value by detailing the process ('fetches the page, extracts title/description/key links') and output format, which aligns with annotations. No contradictions.

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

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

The description is three sentences, each earning its place: purpose, process, use cases. No redundant words, well-structured with front-loaded key information.

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

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

Despite having no output schema, the description fully specifies the output ('single text blob ready to drop at site-root/llms.txt'). Given the tool's simplicity and rich annotations, the description is complete and sufficient for an agent.

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

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

Schema coverage is 100% and both parameters are well-described. The description adds extra detail beyond the schema, such as default (25) and maximum (50) for max_links, and explains the output format, enhancing understanding.

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

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

The description specifies a concrete action ('generate a production-ready llms.txt file') and resource ('for any URL'), clearly distinguishing this tool from siblings like deep_research or scan_competitor_ai_presence by focusing on 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 lists three clear use cases (client site indexing, personal project drafting, competitor audit), providing good context. However, it does not explicitly state when not to use this tool or suggest alternative tools for related tasks.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful context such as returning a 'best-effort live price' and the correct iso.org page, and emphasizes reliability ('resolves any standard via its catalogue id'), going beyond what annotations provide.

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

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

The description is three sentences long, front-loads the core purpose, and every sentence adds value without redundancy. It is efficient and well-structured.

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

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

Given the tool's simplicity (one optional parameter, read-only, idempotent), the description covers all necessary aspects: what fields are returned, how to input the standard, and note on reliability. No output schema exists, but the listed fields are sufficient for understanding the return value.

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

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

The schema already fully describes the 'number' parameter, and the description enhances it by listing valid input formats (e.g., 'ISO-9001', 'ISO 9001:2015') and mentioning that 'reference' is an accepted alias, adding practical guidance beyond schema documentation.

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

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

The description clearly identifies the tool as retrieving a full record for a single ISO standard, listing specific fields returned (title, abstract, status, etc.) and distinguishing it from sibling 'search_standards' which would be for multiple results.

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

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

The description provides clear context for when to use the tool (to get detailed information for a known standard), but does not explicitly mention alternatives like search_standards when the standard number is unknown. The hint to use 'the reliable lookup' is helpful.

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

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

Annotations already declare readOnlyHint true and destructiveHint false. The description adds value by specifying the exact fields returned (id, type, params, timestamps, fire_count) and the option to include inactive subscriptions, providing behavioral context beyond the annotations.

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

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

Two concise sentences: first states the purpose and return fields, second gives usage context. No redundant words, and the critical information is front-loaded.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, returned fields, and appropriate usage context. No gaps are apparent.

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

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

Schema coverage is 100% with the 'include_inactive' parameter well-described. The description implies default behavior (active only) but adds no new semantic details beyond the schema. Baseline of 3 is appropriate.

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

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

The description states 'List the caller's active subscriptions' with a clear verb and resource, and lists the returned fields. It differentiates from sibling tools like 'subscribe' and 'unsubscribe' by focusing on listing rather than mutating subscriptions.

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

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

Explicitly advises using the tool to review current subscriptions before adding more or to find an ID to cancel. While it doesn't name alternatives like 'subscribe' or 'unsubscribe' directly, the context of siblings and the usage hint make the guidance clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns URLs but does not detail output format or behavior beyond what annotations imply.

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, direct and efficient. Every phrase adds value. No redundant information.

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

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

For a parameterless tool providing URLs, the description is nearly complete. It identifies the specific files and license. Minor gap: does not describe the output format (e.g., array of strings) or how to access the URLs, but acceptable given simplicity.

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?

No parameters, schema coverage 100%. Description does not need to add parameter info. Baseline 4 applies per guidelines for 0 parameters.

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

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

Description clearly states the tool provides URLs for ISO Open Data bulk files, listing specific resources (deliverables metadata, ICS classification, technical committees). This is distinct from any sibling tools like search_standards or get_standard.

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 ingest the full dataset yourself', indicating when to use. However, no explicit when-not-to-use or alternatives, though not necessary given the tool's simplicity.

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

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

Annotations are all false and provide no hints, so the description carries the full burden. It discloses rate limits (5 per identifier per day), free usage, that it doesn't count against quota, the claim_token flow, daily digest reading, and roadmap influence. This far exceeds what annotations offer.

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

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

The description is long but every sentence earns its place. It front-loads the purpose, then logically moves through use cases, exclusions, claim_token flow, and limitations. No fluff or repetition; the density is appropriate for the tool's many nuances.

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, no output schema, and 100% schema parameter coverage, the description fills all remaining gaps: return value behavior, rate limits, account handling, and relationship to sibling tools. An agent can safely invoke and follow up on this tool without further clarification.

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

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

Schema coverage is 100%, so baseline is 3. The description adds a meaningful flow explanation for claim_token (filing without an account returns it and can be passed back later), and emphasizes describing issues in terms of Pipeworx tools/packs, which contextualizes the context object. This goes slightly 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 opens with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes feedback from sibling tools like ask_pipeworx or discover_tools, and the scope is explicitly limited to Pipeworx-served tools.

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

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

Provides explicit when-to-use scenarios (bug, feature/data_gap, praise) and a clear when-not-to-use exclusion ('if the tool came from a different MCP server... file it with that server instead'). Names alternatives (other server connectors) and gives a disambiguation rule for identifying Pipeworx tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds that data is derived from CF analytics-engine, no PII is included, and results are cached 5min-1h depending on window. This adds valuable context beyond annotations.

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

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

The description is concise (three sentences), front-loads the purpose, and each sentence adds value. No extraneous information.

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

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

For a simple tool with one parameter, no output schema, and comprehensive annotations, the description covers purpose, usage, param semantics, and behavioral details like caching and data source. No gaps remain.

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

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

Only one parameter 'window' with enum values. Schema coverage is 100%. The description explains the meaning of different windows (shorter for hot right now, longer for steady-state demand), adding semantic guidance beyond the schema's enum description.

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

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

The description clearly states the tool returns the top tools, top packs, and total call volume over a recent window, which is a specific verb+resource combination. It distinguishes from siblings like discover_tools by focusing on trending data derived from other agents' usage.

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?

Three explicit use cases are provided: discovering hot data sources, confirming canonical tool, and aligning use case with agents. It also explains that shorter windows show what's hot right now while longer windows show steady-state demand. No alternative tools mentioned, but the guidance is sufficient.

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 a safe, read-only, idempotent tool. The description adds substantial behavioral context: monotonicity and partition checks, Jaccard similarity filters, placeholder filtering, fill check against live CLOB depth, and warning when an arbitrage signal is not tradeable. 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 long but well-structured and front-loaded. Every sentence adds value. A minor deduction for density, but conciseness is reasonable given the complexity.

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

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

The description covers input options, processing details, edge cases (placeholders, similarity), output format, and references a sibling tool. Despite no output schema, the response structure is clearly explained.

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 significant meaning: it explains the purpose of each parameter, provides concrete examples (slugs, seed questions), and details the internal processing for each mode. This goes far 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 finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes between three modes (trending scan, event, topic) and is distinct 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?

The description explicitly specifies when to use each mode: no args for trending scan, 'event' for a specific market with examples, and 'topic' for cross-event scanning with a seed question. It also references polymarket_fill_risk for custom sizing, providing clear alternatives.

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

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

The description goes far beyond annotations by explaining the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), how edge is computed, what fields each opportunity carries (edge_pp_net, kelly_fraction, etc.), caching at KV level for 1 hour, and diagnostics. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false).

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

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

The description is lengthy but well-structured, with clear sections for model families, tradeable-edge knobs, and response format. Every sentence provides essential information, though it could be slightly more concise without losing depth.

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 lack of output schema, the description fully explains the response structure (by_segment groups, fed_candidates, _diagnostics) and caching behavior. It covers all aspects needed for correct invocation and interpretation.

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

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

All 9 parameters have descriptions in the schema (100% coverage), but the description adds significant context beyond the schema definitions. For example, it explains slippage_pp with Polymarket fee structure and market depth, and min_partition_leg_kelly with why min_kelly doesn't filter partition arbs.

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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and it's built for 'what should I bet on today'. This distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description explicitly says it's for discovering opportunities without paging through hundreds of markets, and it provides detailed guidance on each parameter (e.g., slippage_pp with real-world context, min_liquidity usage). However, it does not explicitly compare to sibling tools or 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 indicate read-only, open-world, idempotent, non-destructive behavior. The description adds behavioral context such as data computed from daily closes (not intraday), snapshot TTL (60 days), and gaps indicating no scans, enhancing transparency.

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

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

The description is detailed but somewhat lengthy, with multiple technical details integrated into a single paragraph. It is front-loaded with the main purpose but becomes dense with response structure, slightly reducing conciseness.

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

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

Despite no output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and limitations (TTL, gaps). It provides sufficient context for an agent to understand data and usage.

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

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

Schema covers both parameters with descriptions. The description adds meaning beyond schema by explaining 'days' as lookback with default/max and 'window' as snapshot family, and details about snapshot generation on cache-miss.

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 provides edge persistence and decay telemetry from daily snapshots, answering specific questions about edge age and decay. It distinguishes itself from siblings like 'polymarket_edges' by focusing on historical trends.

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

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

The description implicitly conveys when to use it (to assess edge persistence) but does not explicitly state when not to use it or provide direct alternatives. However, the context of sibling tools helps differentiate.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint as false, indicating a safe read operation. The description goes beyond by detailing the walking of the order-book ladder, the return fields (verdict, slippage, thin legs, forced_directional_risk), and the risk of partial fills. 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 dense but well-structured, front-loading the core purpose then parameter requirements, mode-specific behavior, and return fields. Every sentence adds unique value without redundancy, achieving clarity in a single cohesive paragraph.

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 enumerates return fields for both modes (e.g., top_of_book, vwap_fill_price, capture_ratio, thin_legs, forced_directional_risk). It also explains the verdict domain and the significance of each field, leaving no critical gaps in the tool's behavior or outputs.

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 tool description adds operational semantics: e.g., how size_usd is interpreted differently in single-market vs basket mode ('max spend on buys, target proceeds on sells' vs 'settlement notional — shares per leg'), and the auto-detection of side for baskets. This enriches the schema information.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth,' distinguishing between single-market and basket modes. It uses specific verbs and resources, and its purpose is distinct from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly tells the agent 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains when not to rely on theoretical overround and warns about partial basket fills leading to unhedged positions, providing clear context and exclusions.

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

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

Annotations already signal read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond that: fees are gross not net, compatibility warnings/codes can appear even when matched pairs exist, temporal_alignment null means unknown rather than aligned, and unmatched legs are skipped into dedicated fields. No disclosed behavior contradicts 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 front-loaded with purpose and modes, then organized into response shape, safety fields, codes, and counters, which helps navigation. It is quite long and somewhat repetitive around temporal semantics and compatibility warnings, so it does not earn a 5, but the density is mostly relevant given the tool's complexity and lack of an 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?

With no output schema, the description documents the return shape in detail: top_spreads_pp, compatibility fields, temporal_alignment, skipped_unclassified, low_confidence_pairs, skipped counters, and fees_note. It also covers null semantics and edge cases, so an agent has enough context to invoke and interpret the tool correctly in both modes.

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 even with no extra parameter explanation. The description adds meaningful mode-level semantics by grouping topic versus explicit kalshi_event_ticker/polymarket_event_slug and clarifying that both modes run the same matcher with the same caveats. This is real but modest added value over 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 identifies the resource and operation: it computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, with two explicit modes. It does not explicitly contrast itself with sibling tools like polymarket_arbitrage or polymarket_edges, so some differentiation is left implicit.

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

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

The description gives concrete when-to-use guidance for both modes: use pre-mapped topic shortcuts for common macros, or explicit ticker/slug for custom pairings, and it warns that pre-mapped topics are not necessarily tradeable. It does not explicitly name alternatives or state when the tool should not be used in favor of a sibling spread/arbitrage tool.

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

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

Annotations already indicate readOnly=true, idempotent=true, destructive=false. Description adds scoping by identifier and behavior when key omitted, complementing annotations without contradiction.

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

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

Three efficient sentences, front-loaded with core functionality, no unnecessary words 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?

Low complexity (1 optional param). Covers both retrieval and listing, scoping, pairing with remember/forget. No output schema, but return behavior is described. Sufficient for agent to use correctly.

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

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

Schema coverage is 100% with a clear description. Description repeats the schema's 'omit to list all keys' inline, adding no new semantic details 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 explicitly states the tool retrieves saved values or lists keys, with verb 'retrieve' and 'list', resource 'value' or 'keys', and distinguishes from siblings like remember and forget.

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

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

Provides clear when-to-use guidance with examples (ticker, address, notes) and mentions how to list all keys by omitting the argument. No explicit when-not-to-use, but strong positive guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds important behavioral context: mark_read flags events as read for subsequent calls, and the feed is persisted. 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 sentences, front-loaded with the main action, no fluff. Every sentence adds necessary detail.

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

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

Given read-only nature, full parameter coverage in schema, and no output schema, the description explains return value structure, filtering options, polling suitability, and alternative access. Complete for the domain.

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

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

Schema has 100% description coverage, so baseline is 3. The description adds value with examples (e.g., 'sec_8k' for type) and clarifies the side-effect of mark_read. This justifies a 4.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying what it returns (source, citation_uri, payload) and how to filter. It distinguishes from sibling tools that manage subscriptions or perform other actions.

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

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

The description provides context for usage: polling is fine, filtering by type and timestamp, and mentions an alternative external endpoint. It lacks explicit when-not-to-use or direct sibling differentiation, but is clear enough for typical use.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds valuable context: multi-source fan-out, fallback mechanism, soft-fail for patents, and output format. It does not detail potential failure modes or latency, which would warrant a 5.

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

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

The description is a single dense paragraph that front-loads purpose with examples. Every sentence adds value. Could benefit from slight restructuring (e.g., separate sections for parameters), but it remains concise and 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?

No output schema, so description covers return values: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. For a tool with 3 parameters and moderate complexity, this is adequate and complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning: 'type' is only 'company', 'since' accepts relative shorthand with suggested defaults, 'value' can be ticker or CIK. This goes beyond the schema.

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

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

The description clearly states the tool provides a change feed for a company covering filings, news, and patents in a given time window. It uses specific verbs and resources ('change feed', 'fans out to SEC EDGAR, GDELT→GNews fallback, USPTO') and distinguishes from the sibling 'entity_profile' tool.

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

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

Explicitly tells when to use ('what's new/latest/updates') and when not to ('Use entity_profile instead when you want the static profile ... regardless of window'). Also provides examples of typical monitoring interval ('30d' or '1m').

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 write operation (readOnlyHint=false) and idempotent (idempotentHint=true). Description adds key context: key-value pair scoped by identifier, persistence differences for authenticated vs. anonymous users, and 24-hour TTL. 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?

Five sentences, each serving a distinct purpose: main action, usage trigger, storage details, persistence, and companion tools. Front-loaded with 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?

Simple 2-param tool with no output schema. Description covers purpose, usage triggers, storage behavior, persistence TTL, and companion tools. Completely adequate for agent to use correctly.

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

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

Input schema covers both parameters with descriptions; schema coverage is 100%. Description adds usage examples (e.g., subject_property, target_ticker) that aid understanding, but schema already provides sufficient meaning. Score 4 for added value over baseline.

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

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

The description clearly states the tool saves data for reuse, uses specific verb 'Save', and distinguishes from siblings by mentioning pairing with recall and forget. Examples like ticker, address, preference add specificity.

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

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

Explicitly tells when to use ('when you discover something worth carrying forward') and provides concrete examples. References sibling tools recall and forget for full lifecycle.

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

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

The description goes well beyond the annotations by disclosing multi-endpoint cascading, graceful degradation when GLEIF/OpenFIGI are unavailable, the `unresolved` field, `figi_candidates` on ambiguous matches, and source labeling for each identifier. These traits are not encoded in the annotations and materially change how an agent should interpret results.

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 user intent and the core action, and nearly every sentence adds useful operational detail. However, the company block is one extremely long run-on with many nested qualifications, which makes it harder to scan; a bulleted or more segmented structure would improve readability without losing 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 tool with only two parameters but complex multi-source behavior and no output schema, the description covers input forms, identifier sources, return fields, ambiguity handling, unresolved reporting, and degradation behavior. An agent has enough information to call the tool correctly and interpret its results across company and drug cases.

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

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

Although the schema already documents both parameters, the description adds crucial semantics: company input also accepts ISIN, the 'ENTITY NAME ONLY' rule prevents a whole noun phrase from being passed, and the bond example clarifies exactly what the FIGI lookup expects. The warning about trailing security-class words is a concrete misuse-prevention detail 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 opens with concrete user phrasings and then states the core action: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes itself from sibling tools by positioning itself as the first-step name-to-ID resolver, and the explicit SUPPORTED TYPES company/drug remove ambiguity about scope.

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

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

The rule 'Use FIRST whenever you have a name but need an ID' is an explicit when-to-use trigger, and the per-type details spell out valid inputs such as ticker, CIK, ISIN, brand, and generic name. It does not explicitly name sibling alternatives for the inverse case (already have an ID), so the when-not guidance is partial rather than complete.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds that the tool probes each entity using ai_visibility_check and ranks results, providing behavioral context beyond annotations.

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

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

The description is concise (5 sentences), front-loaded with purpose, and each sentence adds value. No wasted words.

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

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

Given no output schema, the description explains the return value (ranked list with score, confidence, signal density). Parameter count is moderate, all are covered. Annotations are rich. The description is complete for the tool's function.

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

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

Schema description coverage is 100%, so baseline is 3. The description paraphrases some parameters ('Optional shared context', 'Optional Anthropic API key') but adds no new meaning beyond the schema.

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

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

The description clearly states the verb 'Compare AI visibility' and the resource 'multiple entities'. It distinguishes from the sibling tool 'ai_visibility_check' which handles single entities, and from 'compare_entities' which may have a different focus.

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 mentions the use case 'competitive AI-marketing audits' and gives an example question. It implies when not to use (single entity check), but lacks an explicit exclusion statement.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds valuable behavioral context: partial failures, bundlephobia first measurement delay (5-30s), and graceful degradation with sources_failed. 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 a single dense paragraph. While information-rich, it is not concise and could be better structured. It is front-loaded with purpose but includes many details in one block.

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 description compensates by detailing the return structure (summary block fields, per-advisory detail, links, alternative versions). Covers edge cases like partial failure and ecosystem limitations. Fully sufficient for an agent to understand 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% and description adds minimal extra meaning beyond the schema (accepts scoped packages, version defaults to latest). Baseline 3 is appropriate.

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

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

The description clearly states it is a composite check for npm packages, covering license, advisories, version history, bundle size, and tree-shaking. It distinguishes from siblings by being specific to npm package evaluation, and mentions the one-call convenience.

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

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

It provides explicit use cases ('is X safe/popular/small') and states scope (NPM only in v1) with alternative hint. Lacks explicit 'when not to use' 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 indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that it returns specific fields like reference, title, status, abstract snippet, committee, and iso.org link, providing behavioral context beyond the annotations.

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

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

The description is two sentences, front-loaded with the action, and every sentence adds value. 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?

The description covers the tool's purpose, return fields, and example usage. While it doesn't mention pagination or default limit, the schema covers those details. Given no output schema, the description is sufficiently complete for an agent to use the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add additional parameter-level information beyond what the schema already provides; it only mentions optional filters in general terms.

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 searches the full ISO catalogue by keyword across specific fields (reference, title, abstract) and lists return fields. It distinguishes from siblings like 'get_standard' by specifying it's a search tool for finding standards on a topic.

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

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

The description explicitly says 'Use to find standards on a topic' and provides example queries. It does not explicitly mention when not to use or alternatives, but the context is clear enough for an agent to decide.

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

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

Adds details beyond annotations: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' No contradiction with annotations.

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

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

Single paragraph, front-loaded with the core function, every sentence adds value (purpose, guideline, behavioral detail, pairing advice). 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?

Covers purpose, usage, behavioral details, parameter examples, and pairing with sibling. No gaps given moderate complexity and rich annotations.

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 slight context (e.g., examples of text sources) but largely repeats schema info. Baseline 3 earned.

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 'Semantic search INSIDE a fetched record' with specific verb and resource, and distinguishes from sibling 'ask_pipeworx_grounded' by explaining how they pair.

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 when the record is too big to cram into the prompt' and names alternative 'ask_pipeworx_grounded', 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?

Adds rich behavioral details beyond annotations: requires OAuth, returns subscription id, delivery channel constraints (phone verification, webhook signing, auto-disable). No contradictions with annotations.

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

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

Well-structured with bullet points, front-loaded main purpose. Slightly long but every sentence adds value; minor room for brevity.

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 main context: types, delivery, OAuth requirement, feed availability. Lacks detail on failure handling or how to ensure idempotency, but overall comprehensive for the 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?

Detailed examples for each type's params and delivery options (SMS/email/webhook) with constraints, far exceeding the schema's basic descriptions. Schema coverage is 100%, but adds significant value.

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

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

Clearly states 'Create a proactive monitoring subscription to a live-data event stream' with specific verb 'subscribe' and resource 'alerts'. Distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

Provides explicit requirement for Pipeworx OAuth account and lists supported types with examples. Lacks explicit exclusions or comparisons with sibling tools, 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. Description adds value by explaining the output structure (category-bucketed examples with tool+argument shapes) and that it draws from a live catalog. 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 with the core purpose front-loaded. While it includes a long parenthetical list of categories, it remains compact and free of extraneous 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?

Given no output schema, the description adequately explains the return value (category-bucketed example questions with tool+argument shapes). It covers what the tool does, when to use it, and what to expect, making it complete for its role.

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 a description for `topic`. Description adds semantic value by explaining that omitting the topic gives a cross-category spread, which is not 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's purpose as an onboarding entry point for learning what Pipeworx can do, returning category-bucketed example questions. It distinguishes from sibling tools like discover_tools by specifying it's for getting started and understanding capabilities.

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

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

Explicitly advises using it first when the agent doesn't know what Pipeworx can do. Provides context for getting started and learning about data. While it doesn't list when not to use it, the guidance is clear and specific.

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 (non-destructive, idempotent, not read-only), the description adds key behavioral traits: ownership enforcement, soft deletion (deactivate vs delete), and persistence of historical events. 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 purpose, minimal waste, and efficiently conveys all necessary behavioral details.

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

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

For a single-parameter mutation tool with strong annotations, the description covers purpose, ownership, deactivation behavior, and links to a sibling tool for accessing historical data. No gaps.

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

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

Schema coverage is 100% and the description mentions the 'id' parameter contextually ('by id'), but adds little extra meaning beyond the schema's description of the parameter as a subscription uuid.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource, distinguishing from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

It explains ownership enforcement and that rows are deactivated (not deleted), guiding the agent on when to use this tool (self-cancellation) and mentioning that historical events remain via 'recent_alerts', but lacks explicit when-not-to-use guidance.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description discloses nuanced behaviors: the distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source found), inclusion of verification_error details, and the use of verbatim evidence. This clarifies how to interpret results and avoids false conclusions, going far beyond what annotations convey.

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

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

The description is long but information-dense, front-loaded with trigger phrases and a clear purpose. Each section (when to use, pipeline behavior, output semantics, error handling) earns its place; however, it could be slightly tightened by trimming the repeated claim examples, though they do help 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?

For a tool with no output schema, the description thoroughly covers return values (verdict list, actual value with citation, reasoning), error semantics, and the fallback pipeline. It also explains how this tool integrates with others ('Replaces 4–6 sequential calls'), making it self-sufficient 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?

The schema already provides full descriptions for both parameters, but the tool description adds crucial context for tolerance_pct, such as overriding implied wording, its use in hallucination detection, and the default cap at 5%. This enriches parameter understanding beyond the schema alone.

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

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

The description states a specific verb+resource: 'natural-language claim verification against authoritative sources', and opens with common query phrases that clarify its purpose. It clearly distinguishes itself from siblings like ask_pipeworx or deep_research by focusing on fact-checking with a verdict output.

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 instructs 'Use whenever the agent needs to check whether something a user said is factually correct', and explains the two distinct paths (SEC EDGAR fast path vs. grounded pipeline) with a fallback rule. It also notes that this tool replaces 4-6 sequential calls, giving strong guidance on when to invoke it over a multi-step approach.

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