uiule

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds meaningful context beyond that: the default free Workers AI model, the direct billing to the user when an Anthropic key is passed, and the return structure (per-model score/confidence/signals/raw_response + combined view). This goes beyond the annotations, though it omits details like rate limits or failure modes, so a 4 is appropriate.

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 tight sentences: core purpose, configuration/defaults, and output plus use cases. It front-loads the most important information, and every sentence earns its place with no fluff. Ideal 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?

There is no output schema, but the description compensates by specifying the return shape: per-model {score, confidence, signals, raw_response} plus a combined view. It also covers the required setup (default key, optional API key) and use cases. However, it lacks details about the meaning of 'signals' or confidence scoring, and doesn't mention error/edge cases, leaving a few gaps for a tool of this complexity.

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

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

The schema already provides 100% coverage for all 4 parameters with clear descriptions, so the baseline is 3. The description adds extra semantic value by clarifying the default model (Workers AI) and that `_apiKey` incurs direct Anthropic charges, enriching the meaning of `models` and `_apiKey` parameters. This is more than the schema alone offers, hence a 4.

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

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

The description clearly states the tool's role: 'Probe one or more LLMs for what they know... and score visibility (0-100) per model.' This is a specific verb+resource+outcome, and the scoring aspect sets it apart from general Q&A tools. However, it does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, which may overlap, so it stops short of a 5.

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

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

The description gives concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model plus how to extend via `_apiKey`. It provides clear context on when to use the tool, but does not mention alternatives or when not to use it, so it lacks the explicit exclusion guidance needed for a 5.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral context: returns structured answers with stable citation URIs, works on every tier, is one fast call, and routes to appropriate sources. It does not contradict annotations and enriches the safety profile.

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 key directive, then provides concise examples and clear escalation paths. Every sentence serves a purpose—no fluff. It is long but structured in a scannable way, making it effective for an agent.

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

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

Despite lacking an output schema, the description explains the return format (structured answer with citations) and covers a wide range of usage scenarios. It even mentions handling breaking news and gives example queries, making it complete for an agent to decide and 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% for 6 parameters (all aliases for the same question field). The description does not add substantial meaning beyond the schema; it merely reiterates that the question is natural language. The baseline for high coverage is 3, and the description doesn't compensate with extra semantic detail.

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

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

The description clearly states the tool's purpose: it answers factual questions about real-world data by routing to 5,621 tools. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and explicitly says 'PREFER OVER WEB SEARCH' to set its 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 description provides explicit when-to-use guidance: 'Use whenever the user asks...' with examples, and explicitly says 'START HERE for most questions.' It also names alternatives (ask_pipeworx_grounded, deep_research) and conditions for stepping up, making the choice clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it is a beta with live routing improvements (currently inactive), it has the same response shape as ask_pipeworx, and it is a full functioning router. This goes beyond the annotations and clarifies the experimental nature without contradicting the safety hints.

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

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

The description is three well-structured sentences: first defines the tool, second details current state, third gives usage. It is front-loaded with the core idea and each sentence contributes new information. Slightly wordy but efficient overall.

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

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

For a complex router, the description provides sufficient context: it explains the beta nature, current equivalence to ask_pipeworx, and that responses match ask_pipeworx. It doesn't detail return format, but since it states 'same response shape,' an agent familiar with ask_pipeworx can infer. The annotations cover safety, so nothing critical is missing.

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

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

The input schema covers 100% of parameters with descriptions, including alias definitions. The description does not add any parameter-specific semantics—it merely says 'same arguments' as ask_pipeworx, which is not additional meaning. Since schema coverage is complete, baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a beta variant of ask_pipeworx, a universal router with the same 5,621 tools and response shape. It distinguishes itself from the stable version by mentioning candidate routing improvements, and it explicitly states it is a full working router, not a fallback. This is a specific verb+resource description that differentiates it from siblings like 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 gives explicit guidance on when to use this tool: 'when you want the newest routing.' It also explains that results are compared against the stable router for merging, and that it currently matches ask_pipeworx exactly. While it doesn't mention when not to use it or explicitly contrast with ask_pipeworx_grounded, the condition 'when you want the newest routing' provides clear context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond these by detailing the exact return structure on success and failure (including refusal_reason enum values), the extraction method (only from tool result), and the added latency/cost. This provides meaningful behavioral context not present in annotations.

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

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

The description is dense but efficient, front-loading the core value proposition ('Hallucination-resistant answer mode') and then systematically covering return types, refusal reasons, use cases, and cost. Though several sentences long, every sentence adds operational value without fluff.

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

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

Even without an output schema, the description fully specifies the expected return object including field names and possible refusal_reason values. It also addresses cost and when to avoid this tool. For a one-parameter tool, this is comprehensive and leaves no critical gap for an agent to call 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?

There is a single real parameter, 'question', with five documented aliases, and schema description coverage is 100%. The description does not add additional meaning or usage details for the parameter beyond what the schema already states; the baseline of 3 applies.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It specifies the outcome (returns {answer, evidence, confidence, source, ...}) and the exact use case (quotable, citable answers). It distinguishes itself from 'ask_pipeworx' by emphasizing extraction from tool results only and explicit refusal behavior.

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

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

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups.' It enumerates high-stakes domains (financial verdicts, legal claims, medical lookups, public statements) and even notes the cost trade-off. There is no ambiguity about when to select this tool over its sibling.

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

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

The description is exceptionally transparent, disclosing the resolver contract (confidence levels, match score, alternatives), safety short-circuits (low-confidence suppression of analysis fields), closed/dead market handling, wide-spread tradeability flags, and resolution-rule risk. These go well beyond the annotations and provide critical context for conservative sizing.

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 and densely packed, but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every section adds value and front-loads the core purpose, but the sheer length keeps it from a perfect conciseness score.

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

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

With no output schema, the description carries the full burden of explaining what agents can expect from results. It covers market fields, analysis blocks, evidence keys, parent_event extraction, news fallbacks, and cancellation rules. This is a model of completeness for a complex tool.

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

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

The input schema already describes all three parameters with example values and coverage is 100%. The description adds fan-out examples and response shapes but does not add new meaning to the parameters themselves. Baseline of 3 is appropriate since the schema fully documents them.

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

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

The description gives a specific verb ('Research'), a specific resource ('a Polymarket bet'), and scope ('pulling the relevant Pipeworx data for it in one call'). It distinguishes this tool from siblings like polymarket_edges or polymarket_arbitrage by focusing on a single bet and returning an evidence packet plus market-vs-model comparison.

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

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

The description provides explicit 'Use for' scenarios ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and gives concrete examples of when to trust the result. However, it does not explicitly mention alternative tools or exclusion criteria (when not to use), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description goes further by detailing data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), specific metrics pulled, handling of off-calendar fiscal years, and sorting behavior. This is rich 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 dense but well-structured, starting with trigger phrases to quickly convey intent, then core functionality, usage preference, data details, and return format. Every sentence earns its place with no filler or repetition.

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

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

Given the tool's complexity (two entity types, different data sources, sorting, return format) and absence of an output schema, the description covers all essential aspects: paired data with citation URIs, sorting by primary metric, and the efficiency gain over sequential lookups. It is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and both parameters have descriptions. The description adds value by explaining what each type retrieves (e.g., 'type="company" pulls LATEST 10-K revenue...') and the value constraints (2–5 items). It doesn't add syntax details not already in the schema, but it meaningfully contextualizes the parameters.

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

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

The description explicitly states the tool performs 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call', with specific trigger phrases like 'X vs Y' and 'which is bigger'. It clearly distinguishes from single-entity lookups and names the resource (companies/drugs).

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', and gives concrete examples of comparison intents. It also differentiates between company and drug usage, giving clear context for when each type is appropriate.

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

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

Annotations already establish readOnly, openWorld, idempotent, and non-destructive traits, so the description adds valuable behavioral context beyond that: account/plan requirements, parallel decomposition across 5,621 tools, output packet structure, gaps[] never being invented, citation_uri fetchability guarantees, contradictions[] behavior, semantic excerpting, and latency expectations. No contradiction with annotations exists.

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 the tool is genuinely complex and nearly every sentence carries operational information. It is front-loaded with the most critical constraints (auth, alternative tool, core capability). It loses a point for repetition with the already-rich schema and a somewhat dense, all-caps/parenthetical style.

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 does the necessary work of explaining return contents: findings with verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], and hop fields. It also covers auth, cost, latency, and source scope, so an agent has everything needed to decide and invoke correctly.

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

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

The input schema already covers both parameters at 100%, including detailed depth behavior. The description adds extra decision-relevant context: latency ranges, the paid requirement for 'thorough', and the framing that multi-step questions resolve in one call. This goes beyond the schema but somewhat repeats its depth details, so it is strong but not maximal.

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 and resource: grounded multi-source research across Pipeworx's structured data sources in one call. It explicitly contrasts itself with open-web search and with ask_pipeworx, making sibling differentiation immediate and concrete.

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

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

Usage guidance is explicit and actionable: use it for broad/multi-part questions over structured data, and for single lookups use ask_pipeworx. It also gives an authentication-based exclusion: if not signed in, use ask_pipeworx instead. This directly tells the agent when to select this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it returns top-N tools with names, descriptions, and full input schemas, and results are 'ready to call directly, no second schema lookup needed.' This goes beyond the annotations without contradicting them.

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

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

The description is four sentences, front-loaded with purpose, and logically structured: purpose, usage context, return value, and priority guidance. Though the domain list is long, it is relevant to disambiguate coverage. All sentences earn their place; no wasteful 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?

There is no output schema, so the description correctly explains the return format: top-N tools with names, descriptions, full input schemas, and curated examples. It also lists its coverage domains and gives explicit guidance ('Call this FIRST'). Given the meta-tool nature and rich parameter schema, this is a complete description.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's 'describing the data or task' aligns with the 'query' parameter, but it does not add new meaning beyond the schema's alias documentation (q, task, search, description) and limit details (default/max). It doesn't repeat or elaborate on parameter formats, keeping the schema as the authority.

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

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

The description opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes itself from sibling tools by being a meta-tool (discovering other tools) rather than a domain-specific tool, listing many covered domains. This is a clear, non-tautological purpose statement.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' It does not explicitly name exclusions or alternatives, but the 'not just one answer' contrast implies when a direct call might be preferred. This is clear enough for a discovery tool.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description discloses cross-source fan-out behavior, exact returned sections, patents soft-fail until May 2025, GDELT→GNews fallback, and zero-padded CIK requirement. This is rich behavioral context that annotations don't cover.

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

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

The description is long but densely packed with trigger examples, return structure, fallback behavior, and usage constraints. Every sentence earns its place, though it could be slightly tightened without losing value.

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

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

For a complex multi-source tool with no output schema, the description fully covers expected returns (filings with URIs, fundamentals fields, patents, news, LEI), failure modes, and input constraints. This is complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100% and already documents type and value with examples and the 'names not supported' note. The description repeats this but adds no new semantic meaning beyond what the schema provides, so baseline 3 applies.

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

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

The description opens with concrete trigger examples and states 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from sibling tools like compare_entities or deep_research by specifying the single-entity holistic profile purpose.

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

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

Explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also clarifies when NOT to use: 'names not supported (use resolve_entity first if you only have a name).' This gives clear when/when-not direction.

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 include destructiveHint=true and idempotentHint=true, so the description doesn't need to restate those. It adds value by specifying what is destroyed (a memory by key) and the typical use cases for deletion. However, it doesn't mention irreversibility or edge cases like missing keys, but that's partially covered by annotations.

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

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

The description is two sentences with no wasted words. The first sentence states the core action; the second gives usage triggers. 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 one-parameter delete tool with good annotations, the description provides complete context: what it does, when to use it, and how it relates to sibling tools. No output schema is needed, and idempotency/destructiveness are covered by 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 description coverage is 100%—the single parameter 'key' is described as 'Memory key to delete.' The description's phrase 'by key' adds no extra meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with a clear verb and resource: 'Delete a previously stored memory by key.' It explicitly distinguishes the tool from siblings by framing it as the counterpart to remember and recall, which are listed in the 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 provides explicit usage criteria: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also references complementary tools (remember and recall), giving clear context on when this tool is appropriate versus alternatives.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds behavioral context by explaining it fetches the page, extracts key metadata, and outputs markdown. It stops short of disclosing potential errors or external network dependencies in more detail, but the added process explanation exceeds the annotation baseline.

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 at three sentences, front-loads the primary purpose, and uses a short bullet-like list for use cases. Every sentence adds information without redundancy.

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

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

For a simple two-parameter tool with no output schema, the description adequately covers input (any URL, optional max_links), process (fetch, extract, emit), and output (markdown blob ready for site-root). It does not discuss failure modes or rate limits, but the core context is complete enough for reliable 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?

Input schema coverage is 100% with both url and max_links described. The description does not add meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with a specific verb ('Generate') and resource ('llms.txt file'). It distinguishes itself from siblings by detailing the fetch-extract-emit workflow and naming the output format, which is unique among the listed tools.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting llms.txt for own project, or auditing a competitor. It does not explicitly mention alternatives or when-not-to-use, but the contexts are clear enough to guide selection among siblings like ai_visibility_check or scan_competitor_ai_presence.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the description's addition of 'Returns full text with reference and translation metadata' goes beyond the safety profile by disclosing the return format. This useful context compensates for lacking details about rate limits or auth, which are less critical for a read-only tool.

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

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

The description is two sentences, front-loaded with the core action, and every word contributes meaning. It lists translations efficiently and states the return type without fluff, making it highly concise 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?

For a simple read-only tool with two fully documented parameters, an output schema, and comprehensive safety annotations, the description covers the essential purpose, customizability, and return behavior. No significant gaps remain for an agent to use it correctly.

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

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

Schema coverage is 100%, fully documenting both parameters with examples and translation codes. The description adds minimal value by listing translations in prose, but it does not provide any syntax details beyond the schema, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Get') and identifies the resource ('Bible passage') with translation options, clearly distinguishing it from tools like random_verse and implying specific reference-based retrieval. It mentions the output includes full text and metadata, making the tool's function unmistakable.

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

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

The description does not provide any when-to-use or when-not-to-use guidance, nor does it mention alternatives like get_verse for single verses. The context is limited to what the tool does, without positioning it among sibling tools.

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

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

Annotations already indicate the tool is read-only and idempotent, so the description does not need to restate that. The description adds valuable behavioral context by specifying that the text is returned in the World English Bible translation, which goes beyond the schema.

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 concise sentences, front-loaded with the action and resource, and includes useful examples. Every word earns its place with no redundancy or fluff.

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

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

For a simple tool with one parameter and an output schema, the description is largely complete, covering purpose, examples, and translation. It does not mention error handling or explicitly differentiate from similar sibling tools, but these are minor gaps given the tool's 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?

The input schema already provides full coverage and examples for the 'reference' parameter, including automatic space encoding. The description reinforces the reference format but does not add significantly new meaning beyond what the schema documents.

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

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

The description clearly states the tool retrieves a specific Bible verse or range by reference, with concrete examples. However, it does not explicitly differentiate itself from the sibling tool 'get_passage', which may cause ambiguity about which tool to use for passage 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 gives clear context on valid reference formats and the translation used, implicitly suggesting when to use this tool. However, it does not explicitly state when to use it over alternatives like 'random_verse' or 'search_within'.

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, so the safety profile is covered. The description adds value by enumerating the exact return fields (id, type, params, created_at, last_fired_at, fire_count), which helps the agent understand what to expect without an output schema. It does not mention pagination or ordering, but this is a minor omission for a simple list tool.

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

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

The description is extremely concise—two sentences—with information front-loaded. It covers purpose, return format, and usage in a highly efficient manner, with zero fluff or redundancy.

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

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

For a read-only list tool with one optional parameter and no output schema, the description is complete. It states what the tool does, what it returns, and when to use it. The context signals confirm low complexity, so no additional details are necessary.

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 single optional parameter (include_inactive) that already has a descriptive comment and default value. The description adds no additional parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description opens with 'List the caller's active subscriptions', which uses a specific verb ('List') and a clearly defined resource ('the caller's active subscriptions'). This distinctly differentiates it from sibling tools like subscribe and unsubscribe, which perform different actions on subscriptions.

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

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

The second sentence explicitly states when to use this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear contextual guidance and implicitly points to alternatives (subscribe/unsubscribe) without needing to name them.

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

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

Adds rich behavioral context beyond annotations: claim_token flow, daily digest, rate limit ('Rate-limited to 5 per identifier per day'), and free/no quota. Annotations only cover read/destructive hints, and the description aligns with them without contradiction.

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

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

The description is fairly long (~150 words) but every sentence earns its place: scope, use cases, exclusions, token flow, rate limits, and quota. Front-loaded with purpose, and structured readable. Slightly dense but justified by the tool's complexity.

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

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

Covers when to use, when not to use, what to include, how to follow up (claim_token), and operational constraints (daily digest, rate limit). The absence of an output schema is mitigated by describing the claim_token return. No significant gaps exist.

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 already describes all 4 params at 100% coverage. The description adds extra value by explaining the claim_token lifecycle (filing returns a token, passing it later reads resolution status), which is not fully in the schema. It also reinforces type semantics with real-world scenarios.

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 opens with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It also distinguishes itself from sibling tools (all research/memory/market tools) by being the only feedback mechanism, and elaborates on specific categories (bug, feature, praise).

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

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

Explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives exclusions and alternatives: 'if the tool came from a different MCP server... file it with that server instead.'

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: data provenance ('derived from CF analytics-engine'), privacy ('no PII'), and caching behavior ('Cached 5min-1h'). This goes beyond what annotations provide, though it does not elaborate on exact response structure or error cases.

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

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

The description is efficiently structured: a one-sentence purpose, a clear list of three use cases, and a brief technical note on aggregation and caching. Every sentence adds value, and the most important 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?

Despite having no output schema, the description adequately explains the return contents ('top tools, top packs, total call volume', '(pack, tool, count)') and includes caching and privacy details. For a simple tool with one optional parameter, this is complete and sufficient for an agent to decide whether and how to invoke it.

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

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

The input schema already covers 100% of the parameter, including its enum values and a description explaining the difference between shorter and longer windows. The description repeats the window options but does not add additional semantic meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb ('Returns') and resource ('top tools, top packs, and total call volume'), clearly distinguishing it from siblings like discover_tools. The opening question 'What other AI agents are calling on Pipeworx right now?' immediately conveys the tool's unique purpose.

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

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

Provides explicit use cases in a numbered list (discovering hot data sources, confirming canonical tools, aligning use cases) and explains window selection trade-offs. However, it does not explicitly state when not to use it or name alternative tools, so it misses the full 5 criteria.

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 flag read-only/open-world, but the description adds depth: it explains the partition_check threshold (>3pp), semantic anchor with Jaccard ≥0.30, placeholder filtering, and fill check with realizable_edge_pp ≤ 0 as a falsification. It also warns against trading last-trade overround, going 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 long but logically structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the core mechanism. Every sentence conveys important operational detail, though a few points are reiterated across modes. It earns a high score, but could be tightened slightly.

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

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

Given the tool's complexity (two modes, filters, and a fill check) and no output schema, the description covers return shapes, edge cases (skipped_low_similarity, placeholder fraction >20%), and behavior (null arb signal). It even tells the agent when the signal should not be traded, making it fully contextualized.

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?

Both parameters are already documented in the schema (100% coverage), but the description enriches them with concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), explains what each mode does to the arguments, and notes that full URLs are accepted for `event`. This goes well 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 specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by its methodology and modes.

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

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

It provides explicit mode selection: no args for trending_scan, `event` for single-event, `topic` for cross-event. It recommends event for a specific market and directs users to polymarket_fill_risk for custom sizing, clearly indicating alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes far beyond, disclosing internal model families, edge calculation details (e.g., slippage, Kelly caps), response segments, diagnostics, and caching behavior. It even adds a 24h-move warning, giving agents a clear picture of what the tool does and its limitations.

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 efficiently organized. It front-loads the purpose, then details segments, metrics, knobs, and response structure in logical sections. Every sentence adds necessary behavioral or usage detail for a complex tool; no fluff 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?

Given no output schema, the description thoroughly explains the response top-level structure (by_segment, fed_candidates/fed_note, _diagnostics) and the meaning of each segment. It covers all major behavioral aspects (model families, edge calculation, filters, caching) and provides enough context for an agent to use the tool effectively.

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

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

Schema coverage is 100%, but the description adds deep semantic value: it explains how knobs like min_liquidity and max_spread_pp filter tradeable edges, how min_partition_leg_kelly works differently for partition arbs, and provides concrete tuning suggestions (e.g., 'Set to 2 to require tight books'). This goes well beyond the schema's basic type/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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the exact purpose ('what should I bet on today') and distinguishes itself from sibling tools by describing its segmentation and unique model families.

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 positions the tool for opportunity discovery without paging hundreds of markets, and explains when to use knobs like min_liquidity, max_spread_pp, and min_partition_leg_kelly. It also notes exclusions (e.g., Fed bets are unreliable and excluded from ranking), providing clear usage guidance versus alternatives.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the 60-day TTL limit, cache-miss snapshot behavior (gaps meaning no scan), decay computed from daily closes not intraday, and the detailed response structure (tracked/expired/snapshot_dates). These are non-obvious behavioral traits that the annotations do not cover.

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 with labeled sections (Args, RESPONSE, LIMITS). While long, each sentence adds unique behavioral or semantic value, though it could be slightly condensed without losing meaning.

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

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

Given the absence of an output schema, the description thoroughly enumerates the response fields (edge_pp_net time-series, trend, decay_pp_per_day, lifespan_days, snapshot_dates). It also covers data availability gaps and limitations, making it sufficient for an agent to understand what it will receive and how to interpret it.

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

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

The input schema already covers both parameters (days and window) with clear descriptions. The description repeats the defaults and adds the 'lookback' framing, but no significant semantic addition beyond what the schema provides. Per the rubric, baseline 3 is appropriate when schema coverage is 100%.

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 it provides 'edge persistence and decay telemetry' and frames the core question it answers ('how long has this edge existed and is it shrinking?'). This clearly distinguishes it from sibling tools like polymarket_edges, which likely focuses on current 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?

The description gives strong contextual guidance: 'a fresh wide edge and a 3-week-old wide edge are different trades' and explains the tool is 'built from daily polymarket_edges snapshots.' It implies usage for historical edge analysis, though it doesn't explicitly name alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds rich behavioral detail: it explains how it walks the order book ladder, differentiates single-market vs basket modes, interprets size_usd differently per mode, and reveals the risk of partial basket fills. 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 long but well-structured with 'SINGLE-MARKET' and 'BASKET' labels that break the text into logical sections. Every sentence provides necessary information for a complex tool. However, it is a dense paragraph that could benefit from bullet points; it is borderline verbose but not wasteful.

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

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

Given the tool's complexity (4 params, no output schema, no enums), the description is remarkably complete: it lists return fields for both modes, explains the meaning of size_usd per mode, describes the verdict values, and gives usage context relative to siblings. No critical gaps found.

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 beyond the schema by explaining the dual-mode behavior (single-market vs basket) and how side and size_usd semantics change depending on mode. It also clarifies auto-selection under basket mode. Slightly above baseline but not a 5 because the schema already provides accurate per-param 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 opens with a specific verb+resource+scope: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from siblings by naming polymarket_arbitrage and polymarket_edges, explaining that this tool validates their signals before acting.

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

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

Explicit guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial fills create unhedged directional risk), making the when and when-not 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?

Beyond the read-only/idempotent annotations, the description discloses critical behavioral traits: compatibility_warning conditions (matched_pairs:0 with skipped_cross_type), temporal_alignment semantics, skipped_cross_type/subtype counters, and the expectation that most shortcut topics are not tradeable. It explains what the tool does when data is not comparable, which is essential for correct use.

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 with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). The first sentence immediately states the purpose, and every subsequent sentence adds valuable detail. Given the complexity of the tool, the length is appropriate and not wasteful.

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

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

With no output schema, the description fully explains return values (leg-by-leg prices, spread[].top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It covers edge cases (non-equivalent bet shapes, unrelated events, temporal misalignment) and sets expectations for the rareness of real spreads. This is complete for a tool of this complexity.

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

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

While the schema already describes each parameter at 100% coverage, the description adds deep semantics: it explains the topic list as shortcuts, the override behavior of explicit ticker/slug, and how the two modes interact. It goes beyond the schema by defining the response structure and the meaning of matched_pairs, temporal_alignment, and skipped_cross_type.

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

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

The description clearly states the tool's function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It uses a specific verb (spread) and resource (cross-venue), and the mention of 'same resolving question' and two modes distinguishes it from sibling tools like polymarket_arbitrage.

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

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

The description explains two modes (topic shortcuts vs explicit ticker/slug) and provides guidance on when the spread is meaningful (equivalent bet shapes, temporal alignment). It also warns that 'most pre-mapped topics return compatibility_warning today' and that 'pre-mapped ≠ tradeable,' giving clear usage context even though it doesn't name specific sibling alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds meaningful context by specifying the return payload: reference, full verse text, translation ID, and per-verse breakdown. 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?

Two sentences, zero wasted words. Every piece of information (action, translation, return format) earns its place, and the description is front-loaded with the core purpose.

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

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

The description fully covers what this simple tool does and returns, and an output schema exists to handle structured return details. No parameters or edge cases need explanation. The tool is self-contained even without sibling comparison.

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

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

The tool has zero parameters, so the schema is trivially complete. The description does not need to explain parameters, and the baseline for zero-parameter tools is 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 uses a specific verb ('Fetch') and a clear resource ('a random Bible verse'), and specifies the translation (World English Bible). It distinguishes itself from siblings like get_verse and get_passage by emphasizing randomness, making its purpose unambiguous.

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

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

The description clearly implies when to use this tool (when a random verse is desired) through the word 'random'. However, it does not explicitly mention alternatives or when not to use it, so it misses the 'explicit alternative' criterion for a 5.

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

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint, so the safety profile is known. The description adds valuable behavioral context: the scoping to 'your identifier (anonymous IP, BYO key hash, or account ID)' and the ability to list all keys by omitting the key argument. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences, each earning its place: the first states the core action, the second gives usage context with examples, and the third explains scope and the pair/triad with remember/forget. It is front-loaded and free of fluff.

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

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

For a simple tool with one optional parameter, the description covers purpose, usage, behavioral scope, and the relationship to sibling tools. The lack of an output schema is mitigated by clear statements like 'retrieve a value' and 'list all saved keys', which set expectations without needing further detail.

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 documents the single 'key' parameter with its description 'Memory key to retrieve (omit to list all keys)'. The tool description reinforces this behavior but does not add new semantic details beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses a specific verb, identifies the resource (saved memory values), and differentiates from siblings by explicitly pairing with '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?

It provides explicit guidance on when to use: 'Use to look up context the agent stored earlier' with concrete examples, and distinguishes from alternatives by naming 'remember' and 'forget' as the save/delete counterparts. This gives clear usage context and 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 states that 'mark_read:true' flags events as read, which is a mutating side effect, while the annotation declares readOnlyHint=true. This is a direct contradiction, making the transparency score the lowest possible per the rubric.

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, front-loaded with the purpose, and every sentence adds value without redundancy. It is concise 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?

The description covers return format, filtering, and the side effect of mark_read, but the contradiction with the readOnlyHint annotation creates ambiguity about the tool's safety profile. This prevents it from being fully reliable for an agent, despite covering most functional aspects.

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

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

The description adds meaningful semantics beyond the schema: it explains the effect of mark_read, gives an example for type ('sec_8k'), clarifies that since is an ISO timestamp, and describes the return fields. This goes beyond the baseline 3 given the high schema coverage.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed) and the verb (pull), and distinguishes from sibling tools like recent_changes by focusing on alerts.

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

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

The description gives context on when to use this tool (for polling) and provides an alternative for scripts and dashboards (GET registry.pipeworx.io/alerts.json). However, it doesn't explicitly compare to sibling tools or state when not to use it, so it lacks full exclusionary 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 readOnly/idempotent annotations, the description richly details behavior: it fans out to multiple sources, describes GDELT→GNews fallback logic, notes the USPTO soft-fail due to API sunset, and discloses the output structure (changes[] grouped by source, total_changes, pipeworx:// citation URIs). This exceeds what annotations alone could 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 dense but every sentence adds value. It opens with user-facing query patterns, then moves to data sources, parameter behavior, return format, and an alternative tool. No fluff or redundant restatement of the tool name.

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 multi-source tool with fallbacks and no output schema, the description is remarkably complete. It covers all three parameters, source-specific behaviors, error/soft-fail conditions, return shape, and how to choose between this and sibling tools. Nothing critical appears 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% but the description adds meaningful guidance for the `since` parameter: it explains ISO vs relative shorthand with examples and recommends '30d' or '1m' for typical monitoring. It also clarifies the output structure, which indirectly helps parameter understanding. Minor deduction because type and value semantics are already fully 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 with specific verbs and resources: it provides a change feed for a company over a time window, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. It distinguishes itself from the sibling entity_profile by explicitly noting when to use that alternative for static profiles.

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

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

Usage context is explicit: it shows example queries ('What's new with X'), explains the time-window parameter, and gives a clear alternative ('Use entity_profile instead when you want the static profile...'). This tells the agent both when to use this tool and when to choose a different one.

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

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

Annotations already indicate idempotent and non-destructive behavior, but the description adds essential context: memory is 'scoped by your identifier', persistent for authenticated users, and retained only 24 hours for anonymous sessions. It also clarifies overwrite semantics (key-value pair) which goes beyond the raw 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 compact and front-loaded: first sentence states the purpose, second gives usage guidance, third explains storage semantics, and fourth covers persistence and companion tools. Every sentence adds new information without redundancy.

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

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

For a simple memory-write tool, the description covers purpose, when to use, persistence behavior, and how to complement it with recall/forget. The schema fully documents both parameters, and no output schema is needed for a write operation. The description is sufficient.

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

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

The schema already describes both key and value with examples, so baseline is 3. The description enriches semantics by explaining that the key-value pair is scoped by the caller's identifier and gives concrete usage examples (ticker, address, preference, research subject), which clarifies what should be stored in each parameter.

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 'Save data the agent will need to reuse later' — a specific verb+resource that clearly identifies the tool's function. It also distinguishes from siblings by naming companion tools 'recall' and 'forget' and describing the memory lifecycle.

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

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

The description explicitly states when to use: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject)' and provides an isolation criterion ('so you don't have to look it up again'). It also names alternatives for retrieval and deletion, making the choice clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds significant behavioral detail: internal cascading lookups across multiple sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), graceful degradation if sources are unavailable, explicit listing of unresolved identifiers, and the inclusion of ownership relationships for LEI. 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 long but well-structured: it opens with example queries and purpose, then a usage guideline, then detailed supported type sections. Every sentence earns its place by adding specific information. It could be slightly more concise, but the complexity of the tool (multiple sources and fallbacks) justifies the length.

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

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

Given the tool has no output schema, the description thoroughly explains return values for both entity types, including identifiers from multiple sources, ownership data, unresolved items, and graceful degradation. It covers all necessary context for an agent to understand what the tool returns and how it behaves.

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%, providing clear parameter descriptions. The description adds value beyond the schema by noting that the 'value' parameter for company can also accept an ISIN (e.g., 'CH0038863350'), which resolves to the legal entity via GLEIF mapping. This is a meaningful addition not present in the schema.

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

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

The description clearly states that the tool resolves user-spoken names to canonical identifiers required by other tools. It provides concrete query examples and explicitly says 'Use FIRST whenever you have a name but need an ID,' which distinguishes it from sibling tools like entity_profile that likely require an ID as input.

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 a strong when-to-use directive ('Use FIRST whenever you have a name but need an ID') and notes that it replaces 2-3 manual lookups. However, it lacks explicit when-not-to-use guidance or direct naming of alternative tools for cases where the user already has an identifier.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context by explaining the process (probes each entity), ranking logic, and return format (score, confidence, signal density), which goes beyond the annotations and schema.

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

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

The description is three concise sentences, front-loaded with the core action, and includes a use case and output summary without any filler. Every sentence earns its place, making it highly efficient.

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

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

With no output schema, the description compensates by explicitly stating return values (ranked list with score, confidence, signal density). It also covers the process, use case, and parameter context (via schema), making it complete for a tool of this complexity.

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

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

Schema coverage is 100% with all parameters described in detail. The description does not add significant semantic value beyond the schema; it only rephrases the entities parameter ('your brand + N competitors') already covered by the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'), and clearly distinguishes this from sibling tools by stating it probes each entity with ai_visibility_check and ranks them. This is a clear, specific purpose that differentiates from single-entity check tools.

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

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

The description provides clear context: 'Useful for competitive AI-marketing audits' and gives an example query. However, it does not explicitly name alternatives or state when not to use this tool versus ai_visibility_check or compare_entities, but the 'side-by-side' comparison implicitly covers the main usage scenario.

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

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

Description adds rich behavioral context beyond annotations: 'Partial failures degrade gracefully', 'bundlephobia's first measurement on a new version can take 5-30s', and 'sources_failed will list it if it times out'. This explains latency and error handling, complementing the read-only/idempotent annotations without contradiction.

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

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

The description is dense but well-structured, with each sentence adding value. It front-loads the core purpose, then usage, return format, ecosystem scope, and failure behavior. Slightly long but every sentence earns its place; no redundant words.

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

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

Given no output schema, the description thoroughly explains the return value: summary block with specific fields, per-advisory detail, links, and recent versions. It also covers ecological limitations, latency, and partial failure handling, making it complete for a composite tool.

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

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

Schema description coverage is 100%, so baseline is 3. Both parameters are adequately described in the schema (package name, version defaulting to latest). The description does not add new parameter semantics but reinforces context by mentioning npm ecosystem and return fields like is_latest.

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

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

The description clearly states the tool's function: a composite 'should I add this npm package' check that fans out to deps.dev and bundlephobia. It specifies the data sources and what each contributes, distinguishing it from sibling tools like deep_research or validate_claim.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also provides exclusions and alternatives: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Beyond the annotations, the description discloses concrete behavioral details: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char overlapping windows, and truncates+flags inputs over 200K chars. No annotation 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 four sentences and front-loaded with the primary action, then covers use-case, pairing, and technical limits. It contains no filler, though it is dense and could arguably be trimmed.

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

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

Even without an output schema, the description explains what is returned (passages with offsets and similarity scores), handles large-input behavior (truncation and flagging), and describes how to pair with ask_pipeworx_grounded. This is sufficient for an agent to invoke the tool correctly.

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

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

The schema already describes all parameters (100% coverage), so the baseline is 3. The description adds practical context—'text you already pulled' clarifies provenance, 'top-N passages' explains the effect of limit, and the query examples enrich the natural-language intent.

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 'Semantic search INSIDE a fetched record,' naming a specific verb and resource, and gives concrete examples (SEC 10-K, article, long tool result). This clearly distinguishes it from sibling tools like ask_pipeworx and get_passage.

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

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

It explicitly states the intended use case ('Use when the record is too big to cram into the prompt') and names a complementary tool (ask_pipeworx_grounded). However, it does not explicitly list when not to use the tool or mention alternative tools beyond the pairing, so it stops short of full exclusion guidance.

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

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

The description adds substantial behavioral context beyond the annotations: OAuth account requirement, anonymous/BYO limitation, SMS verification and daily cap, webhook auto-disabling after failures, and one-time delivery of the signing secret. This goes well beyond the safety hints.

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

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

The description is dense but well-structured. It front-loads the purpose, then details types and delivery channels in a scannable format. Every sentence carries necessary information.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description covers the return value, supported types, delivery options, requirements, and failure behavior. It is highly complete.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description adds useful context like the always-on feed and examples of type-specific params, providing a bit more meaning than the schema alone.

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

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

The description clearly states the tool's purpose: creating a proactive monitoring subscription to a live-data event stream and returning the subscription ID. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides clear context on when to use this tool, including supported types and prerequisites like OAuth account and phone verification. It doesn't explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description builds on this by detailing the return structure (category-bucketed example questions with tool+argument shapes), the live catalog source, and the effects of calling with/without the topic parameter. No contradictions.

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

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

The description is a single dense paragraph, front-loaded with realistic query examples and progressing logically to return details and usage. Every sentence contributes, though a few phrases (like 'the onboarding entry point for an agent that just connected') are slightly redundant and could be tightened 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?

With no output schema, the description fully compensates by explaining the return format, category list, and the inclusion of exact tool+argument shapes. It also covers the parameter semantics and provides situational guidance, making it complete for an agent to decide when and how to invoke the tool.

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

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

The schema provides only a basic description of the topic parameter, while the description adds concrete examples ('finance', 'pharma', 'betting'), explains the full list of categories, and clarifies that omitting the parameter yields a cross-category spread. This adds significant 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 as an onboarding entry point that suggests example questions and maps them to exact tool+argument shapes. It distinguishes itself from siblings by emphasizing 'Use this FIRST' and naming meta-tools, making its unique role unmistakable.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.)'. It also explains the optional topic parameter and the behavior when omitted, giving clear context without cluttering.

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=false, destructiveHint=false, and idempotentHint=true, but the description goes beyond by disclosing the ownership restriction and the soft-delete behavior ('The row is deactivated (not deleted)'). These are critical behavioral traits not captured in annotations, making the tool's side effects fully transparent.

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 the primary action, and each sentence carries essential information: the action itself and the key behavioral constraints. Zero redundancy or filler, perfect for quick agent parsing.

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

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

For a single-parameter mutation tool, the description covers ownership enforcement and the non-destructive deactivation, which are the key contextual details. It does not mention return values or error handling, but given the simplicity and the annotations (idempotent, openWorld), this is a minor gap. The tool is adequately complete for an agent to use safely.

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

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

Schema coverage is 100% with a clear parameter description, so the baseline is 3. The description adds minimal extra value by noting the id is 'returned by subscribe,' which is a minor linkage to the sibling tool but does not introduce new 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 opens with 'Cancel a subscription by id,' a specific verb+resource statement that clearly differentiates it from siblings like 'subscribe' and 'list_subscriptions.' Mentioning the deactivation behavior further clarifies its exact scope, making the purpose unambiguous.

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

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

The description provides clear context by stating ownership is enforced (only your own subscriptions) and that deactivation preserves history via recent_alerts, which implicitly tells the agent when to use this tool and what the consequences are. However, it does not explicitly contrast with alternatives, so it misses the top score.

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

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

The annotations already declare readOnly, openWorld, idempotent, and non-destructive, and the description adds crucial behavioral nuance: the distinction between 'could_not_verify' (check did not happen, not evidence) and 'unsupported' (no source), plus the existence of verification_error{stage,detail}. It also discloses the verbatim evidence and citation behavior, which goes well beyond annotation coverage.

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

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

The description is longer than average but every sentence contributes value: examples, routing rules, verdict list, and error semantics. It is front-loaded with the tool's purpose and usage intent. The length is justified by the tool's complexity and the absence of an output schema, though it could be tightened slightly.

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

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

For a tool with no output schema, the description thoroughly explains return values (verdict enum, actual value with citation, reasoning) and edge cases ('could_not_verify' vs 'unsupported'). It also describes the internal routing logic, which helps an agent set expectations. This is a complete description for a claim-verification 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?

The input schema already provides complete parameter descriptions for both 'claim' and 'tolerance_pct', including examples and the tolerance override semantics. The tool description itself does not add new parameter-level meaning; it only references 'exact percent-delta math' in passing. Since schema coverage is 100%, a baseline score of 3 is appropriate.

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

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

The description opens with natural-language query patterns ('Is it true that…', 'fact check') and directly states the tool's job: natural-language claim verification against authoritative sources. It clearly distinguishes its consolidated scope by noting it replaces 4–6 sequential calls, which separates it from siblings like resolve_entity or 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?

It explicitly instructs 'Use whenever the agent needs to check whether something a user said is factually correct.' It also distinguishes between company-financial claims (SEC EDGAR fast path) and any other factual claim (grounded pipeline), which is a practical routing guideline. It doesn't explicitly name sibling alternatives to avoid, but the 'Replaces 4–6 sequential calls' line implies when to prefer this tool.

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