Carbon Interface

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

The description adds important behavioral context beyond the annotations: default model is free Workers AI, optional Anthropic requires BYO key and direct payment, and per-model return structure is specified. This goes beyond the readOnlyHint/idempotentHint annotations and gives the agent actionable cost/billing awareness.

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

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

The description is concise, with three sentences that front-load the core purpose, then detail the model options and return format, and finally suggest use cases. Every sentence adds value with no repetition or waste.

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 explicitly lists the per-model return fields ({score, confidence, signals, raw_response}) and combined view. It covers model selection, API key handling, cost, and use cases, making it complete for a probing tool with moderate 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 description coverage is 100%, so the schema already documents all four parameters. The description adds a little extra context (e.g., default model, BYO key implication) but does not significantly enhance parameter understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100) per model. The verb 'probe' and resource 'LLMs' are specific, and the description distinguishes it from sibling tools by focusing on scoring model knowledge.

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

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

The description provides clear use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) that indicate when to use the tool. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of a perfect 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds rich behavioral context beyond that: it returns 'structured answer with stable pipeworx:// citation URIs,' 'fills arguments' automatically, 'works on every tier, one fast call,' and implies a trade-off by noting that ask_pipeworx_grounded is more hallucination-resistant. This goes well beyond the annotation 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 long (~180 words) but well-structured and front-loaded: it opens with the key directive, then explains function, usage, examples, and alternatives. Every sentence provides useful information, and the length is justified by the tool's broad scope. It could be tightened slightly, but this is strong.

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

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

Despite no output schema, the description covers the return format ('structured answer with stable pipeworx:// citation URIs'), usage scope, examples, alternatives, and even availability ('works on every tier'). It provides enough context for an agent to decide when to use this tool and what to expect, making it nearly complete for a default entry-point 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%: the question parameter is fully described, including aliases. The description does not add extra parameter-level detail beyond saying 'fills arguments,' which refers to the underlying tools rather than this tool's parameters. Baseline 3 is appropriate since the schema already handles parameter documentation.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Routes the question to the right one of 5,462 tools across 1419 verified sources, returns the structured answer with stable pipeworx:// citation URIs.' It distinguishes itself from siblings by being the 'default entry point' and explicitly naming alternatives like ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit when-to-use guidance, starting with 'PREFER OVER WEB SEARCH' and listing categories (SEC filings, FDA drug data, economic statistics, etc.). It gives concrete examples like 'current US unemployment rate' and clearly states when to step up to alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.'

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

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

The description adds significant behavioral context beyond the annotations: it explains the beta nature, that no candidate is currently active, that it matches ask_pipeworx exactly right now, and that it may change live. It also clarifies that it does not fall back to another tool, being a fully functional router. This greatly exceeds the annotation 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 reasonably concise and front-loaded with the essential beta status. It contains four sentences, each providing distinct value: beta definition, current state, usage instruction, and operational clarification. It could be slightly tightened, but the structure is logical and information-dense without being excessive.

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 is complete for a tool that is explicitly a variant of ask_pipeworx. It mentions identical tools, arguments, and response shape, so an agent can refer to ask_pipeworx for details. It covers current behavior, usage, and experimental context. Minor gap: it does not describe the nature of the routing or question types, but this is compensated by pointing to ask_pipeworx.

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

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

The input schema has 100% coverage with descriptions for the required 'question' parameter and all aliases. The description adds no additional parameter-specific semantics beyond stating 'same arguments' as ask_pipeworx. Since the schema already fully documents parameters, a baseline of 3 is appropriate.

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

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

The description clearly identifies this as the beta version of ask_pipeworx and states it is an identical universal router with the same tools and response shape. It distinguishes itself from the sibling ask_pipeworx by emphasizing the experimental routing improvements, but it assumes familiarity with ask_pipeworx to fully understand the 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 is provided: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' This tells the agent when to use this tool and names the alternative (stable ask_pipeworx), making the usage context 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?

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by explaining refusal reasons, evidence format, and the exact structure of success vs. refusal responses. It also discloses the extra LLM call cost. No contradiction with annotations.

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

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

The description is long but well-structured: it front-loads the core concept, then details behavior, refusal reasons, and usage guidance. Every sentence adds meaningful information, though it is denser than strictly necessary for a simple tool.

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

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

Although no output schema exists, the description fully specifies the return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and all possible refusal reasons. This makes the tool's behavior completely understandable for an agent deciding whether to use 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?

Input schema coverage is 100% and already documents the 'question' parameter and its aliases. The description adds context that the question is in natural language and that the tool 'fills arguments' internally, but does not provide additional parameter-level semantics beyond what the schema offers.

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, distinctive purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly states what the tool does (extracts answers using only tool result content) and differentiates from the sibling 'ask_pipeworx' by emphasizing evidence and refusal behavior.

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

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

Explicit usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' It also mentions the cost trade-off (one extra LLM call), giving clear when-to-use and when-not-to-use context relative to alternatives.

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

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

Annotations mark this readOnly, idempotent, and non-destructive, and the description goes far beyond that by detailing resolver contract (market_match_confidence, alternatives, suggestions), safety short-circuits (status:'low_confidence_match'), closed/dead market behavior (status:'market_closed_or_inactive'), wide-spread illiquidity flags, and cancellation-rule parsing. This is exemplary transparency.

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

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

The description is long but tightly structured with header-style labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY). It front-loads the core purpose and usage, then packs advanced contract details into scannable sections with minimal fluff.

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

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

With no output schema, the description takes on the burden of explaining return shapes and statuses, which it does in detail: result.market fields, result.analysis with edge warnings, evidence keying, resolver match fields, parent_event, news fallback metadata, and status codes. It covers safety and cancellation risk, leaving little ambiguity for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description repeats the market parameter's flexibility (slug/URL/question text) already in the schema and adds fan-out examples but no new parameter semantics. For depth and include_raw, the schema carries the full weight.

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 first sentence states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' which is a specific verb+resource and clearly distinguishes this from sibling tools like polymarket_arbitrage and polymarket_edges. It also lists concrete use cases ('should I bet on X'), further clarifying 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 explicitly provides usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives examples and explains edge cases (low-confidence, closed markets) where the tool blocks. It doesn't explicitly name alternative tools to use instead, but the use-case framing is clear.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds extensive behavioral detail: data sources (SEC EDGAR/XBRL, FAERS/FDA), correct handling of off-calendar fiscal years, sorting by primary metric, and return format with citation URIs. This far exceeds 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?

Although long, the description is front-loaded with trigger phrases and priority guidance, and every clause contributes value (data sources, sorting, fiscal years, return format). There is no fluff or repetition of schema details.

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

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

For a tool with no output schema, the description is remarkably complete: it covers invocation triggers, parameter shape, data sources, behavioral nuances (fiscal year handling, sorting), return format, and even the performance benefit (replaces 8–15 lookups). No significant gaps remain.

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

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

Schema already describes both parameters with 100% coverage. The description adds meaningful context by explaining what each type retrieves (latest 10-K financials for companies, adverse-event/trial counts for drugs) and gives concrete examples for the values array, enriching the schema's semantics.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single call, with explicit trigger phrases like 'X vs Y' and 'which is bigger'. It also distinguishes itself from sequential single-entity lookups, 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 explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides trigger phrases that indicate when to invoke. It also explains the different data sources for company vs drug types, offering clear guidance on appropriate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context: account/paid requirements, 15-90s latency, gap[] and contradictions[] arrays, semantic excerpting, hop fields, and the guarantee that citations are resolvable. No contradiction with annotations.

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

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

The description is long but dense and well front-loaded with the critical account warning and core differentiator. Each sentence carries useful information, though it reads as a single sprawling paragraph. For a tool this complex, the length is justified, but improved structure would raise it further.

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

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

No output schema exists, so the description must explain return values—it does: 'findings packet', 'verbatim evidence + confidence + source + fetched_at + stable pipeworx:// citation', gaps[], contradictions[], hop field. It also covers timing, account tiers, and source scope, making it fully complete for an agent to decide invocation and interpret results.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning beyond schema by detailing facet counts per depth ('quick=3', 'standard=5', 'thorough=8') and what each depth's hop behavior entails, plus clarifying that the question can be broad/multi-part. This elevates it to 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 performs 'grounded multi-source research' across Pipeworx's 1419 structured data sources, with a specific verb and resource. It distinguishes itself from siblings by explicitly contrasting with ask_pipeworx for single lookups and noting it is NOT open-web search.

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 vs alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and notes the sign-in requirement with fallback. Also explains depth levels and typical use cases like comparing X and Y.

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 and idempotentHint, covering safety. The description adds behavioral details about returning top-N results with full schemas and examples, and being ready to call directly. It does not contradict 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, with each sentence serving a purpose. The domain list is extensive but provides useful search context without being redundant.

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

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

Given the annotations and full schema, the description adequately covers the tool's behavior, output, and usage context. It even mentions the output format, compensating for lack of an output schema.

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

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

Schema coverage is 100%, so the description need not compensate. It adds slight context via 'top-N' relating to the limit parameter, but doesn't enrich parameter semantics beyond the schema.

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

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

The description clearly states the tool's function with 'Find tools by describing the data or task' and lists specific domains, distinguishing it from sibling tools that perform specific tasks. It also positions it as a discovery meta-tool.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available', giving clear guidance on when to use it versus calling a specific tool directly.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context beyond that: 'fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF,' the 'ONE parallel call' execution model, the 'patents... soft-fails until reactivated' caveat, and the 'GDELT→GNews fallback' chain. It also discloses return field specifics (cik, recent_filings with URIs, fundamentals sorted by period_end DESC). 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?

Although the description is long, every sentence contributes: user-intent examples, core function, preference rule, data sources, return components, fallback behavior, and input constraints. It is front-loaded with recognizable queries and uses compact punctuation (slashes, semicolons) to pack information efficiently. There is no filler or tautological phrasing.

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

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

The tool has no output schema, so the description must explain return values. It does so thoroughly, enumerating expected outputs: cik + company_name; recent_filings (up to 5 with pipeworx URIs); fundamentals (LATEST 10-K metrics, sorted); patents; news via fallback; and LEI. It also covers edge cases like patent sunset and input limitations (ticker/CIK only). This is complete for a complex multi-source 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% (both 'type' and 'value' have descriptions). The tool description repeats the schema's ticker/CIK examples and the 'names not supported' constraint but does not add new parameter-level meaning beyond what the schema already provides. Baseline of 3 is appropriate because the schema carries the semantic load.

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

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

The description opens with concrete user intents ('Tell me about X' / 'research Acme') and then defines the tool as a 'full cross-source profile of a US public company in ONE parallel call.' It clearly identifies the resource (US public companies) and the scope (multi-source profile), and distinguishes itself from sibling tools: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and 'use resolve_entity first if you only have a name.' This satisfies the specific verb+resource+scope criterion and differentiates from alternatives.

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

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

Explicit usage guidance is present: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' tells the agent when to choose this tool. It also defines an alternative path: 'names not supported (use resolve_entity first if you only have a name).' This is clear when-to-use and when-not-to-use guidance with named 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 useful behavioral detail by specifying that emissions are returned in grams, kg, and metric tons, which goes 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 concise, front-loaded with the purpose, and includes a helpful example. Every sentence adds value without unnecessary 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?

An output schema exists, so return values are handled elsewhere. The description covers the core purpose and example usage, but the example's omission of the required _apiKey is a notable gap that reduces completeness for an agent trying 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?

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds an example that clarifies value/country/unit mapping, but it omits the required _apiKey from the example, which could mislead an agent into thinking the API key is unnecessary.

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 estimates CO2 emissions from electricity usage, with a specific verb and resource. It also mentions the return format (grams, kg, metric tons), fully distinguishing it from sibling tools like estimate_flight and estimate_vehicle.

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 that this tool is for electricity usage, which distinguishes it from sibling estimates. However, it does not explicitly state when not to use it or provide alternative tool names, so it lacks explicit exclusions or 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 and destructiveHint=false, covering the safety profile. The description adds that it 'returns per-passenger and total carbon emissions,' disclosing the output format without contradicting the annotations. No mention of rate limits or API key handling, but the annotations lower the burden.

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

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

Three sentences and a compact example deliver purpose, inputs, outputs, and a usage pattern with zero wasted words. The first sentence is front-loaded with the core purpose, making it easy to scan.

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

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

With rich annotations and a fully covered schema, the description covers purpose, inputs, outputs, and provides a worked example. It does not discuss edge cases or the required _apiKey, but the schema already marks it required. Completeness is strong for a simple estimation tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that 'passengers' and 'legs' are provided structurally, and the example illustrates the nested leg object with IATA codes. This natural language explanation complements the schema descriptions.

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

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

The description opens with 'Estimate CO2 emissions from a flight,' a specific verb-resource pair that clearly distinguishes this from sibling tools like estimate_electricity and estimate_vehicle. The scope (flight) and output (CO2 emissions) are 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 states what inputs to provide ('number of passengers and flight legs...') and includes a concrete example, making the invocation context clear. It does not explicitly name alternative tools for non-flight emissions, but the resource scope ('from a flight') implies the appropriate use case.

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 useful context—that it relies on the Carbon Interface API and returns emissions in grams, kg, and metric tons—but does not disclose potential errors, rate limits, or authorization requirements beyond the schema's _apiKey parameter. This is comparable to the calibration example where annotations cover safety and description adds moderate context.

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

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

The description is three sentences: purpose, required inputs, and output units, followed by an example. Every sentence contributes valuable information, and the most critical details are front-loaded. It is appropriately concise without unnecessary elaboration.

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 a full output schema, 100% parameter coverage, and strong annotations, the description does not need to explain return structures or safety. It adds the external dependency (Carbon Interface) and output units, making it complete for an estimation tool. The absence of explicit sibling alternatives is a minor gap, but the description adequately contextualizes the tool's role.

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

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

Schema coverage is 100% with descriptions for all four parameters, so the baseline is 3. The description adds an example call that clarifies positional ordering and unit semantics, but it does not provide additional meaning beyond what the schema already conveys. The example array in the schema further reduces the need for extra parameter explanation.

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: "Estimate CO2 emissions from driving a vehicle." It uses a specific verb and resource, and the phrase "driving a vehicle" distinguishes it from sibling tools like estimate_electricity and estimate_flight. The example call further reinforces the purpose.

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

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

The description provides a concrete example with arguments, implying how to use the tool. It mentions the prerequisite of a Carbon Interface vehicle model ID and shows the expected unit parameter. However, it does not explicitly exclude alternative tools or state when to prefer this over estimate_flight or estimate_electricity, though the scope is clear.

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

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

Annotations already provide destructiveHint and idempotentHint, and the description reinforces the destructive nature by saying 'Delete' and 'clear sensitive data.' It adds context about what is destroyed ('previously stored memory') and why (stale or sensitive), though it doesn't disclose edge cases like missing keys. This is consistent with annotations and adds some behavioral context beyond the hints.

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

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

Three short sentences: the first states the action, the second specifies when to use it, and the third references sibling tools. Every sentence contains essential information and there is no redundancy or padding.

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

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

The tool is a simple single-parameter delete operation with no output schema. The description covers its purpose, use cases, and companion tools, while annotations handle safety/destructive flags. It is fully contextual for the agent to invoke it correctly.

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

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

The input schema already fully describes the 'key' parameter as 'Memory key to delete' (100% coverage). The description repeats 'by key' without adding new syntax, format, or additional parameter details, so it does not exceed the schema's semantic contribution.

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 'Delete a previously stored memory by key,' which is a specific verb (delete) and resource (memory) that clearly distinguishes the tool from siblings like remember and recall. It unambiguously states the primary function.

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

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

The description gives explicit usage triggers: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also says 'Pair with remember and recall,' naming companion tools and suggesting alternatives by contrast.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context: fetching the page, extracting title/description/key links, emitting standard llms.txt format, and producing a single text blob ready for site-root placement. All consistent 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 compact and front-loaded. The first sentence states the core purpose, the second explains the process and output, and the third lists use cases. Every sentence earns its place with no redundancy.

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

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

For a simple tool with 2 parameters and no output schema, the description covers the output format ('standard llms.txt markdown format', 'single text blob') and the intended deployment location ('site-root/llms.txt'). Annotations cover safety. No critical gaps.

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

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

Schema coverage is 100% and both parameters are well documented. The description says the tool 'fetches the page, extracts title/description/key links' which indirectly mentions url usage but adds no new semantics beyond the schema. Baseline score of 3 applies.

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

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

The description opens with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It clearly distinguishes itself from sibling tools by focusing on generating the standard llms.txt file, not just checking or scanning AI visibility.

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 ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor') which conveys when to use. It doesn't mention alternatives or when-not-to-use, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds useful behavioral context: it lists the caller's subscriptions (not all subscriptions) and specifies the return fields. This goes beyond the structured 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 two sentences: the first states the primary action and output, the second gives concrete use cases. Every sentence earns its place with zero 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 the tool's low complexity (one optional parameter), strong annotations, and explicit output field list, the description fully equips an agent to select and invoke the tool. No output schema exists, so listing the return fields is sufficient. The usage guidance completes the picture.

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

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

The only parameter, include_inactive, has 100% schema description coverage ('Include cancelled subscriptions in the response (default false)'). The tool description implicitly reinforces the notion of 'active' subscriptions but adds no new semantic detail, so the 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 uses a specific verb ('List') and resource ('the caller's active subscriptions'), clearly differentiating it from siblings like subscribe, unsubscribe, and recent_alerts. It also enumerates the exact fields returned, leaving no ambiguity about what the tool does.

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

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

The description provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies when to use it relative to subscribe/unsubscribe, though it does not explicitly exclude cases or name alternatives, so it falls short of a perfect 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 description discloses rich behavioral context beyond annotations: the claim_token flow for later status checks, rate limiting ('5 per identifier per day'), the fact that it's free and doesn't count against quota, and that the team reads digests daily. It also explains the dual mode (submitting feedback vs. reading a previous report via claim_token). This goes well beyond the sparse 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 every sentence serves a purpose: use cases, exclusions, claim_token mechanics, rate limits, and roadmap impact. It is well-structured, starting with the main action and then elaborating on context. No fluff or redundancy; length is 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?

Given the tool has nested parameters and no output schema, the description fully explains expected behavior: what happens when filing without an account (returns claim_token), how to use that token, and what to expect in return. It also covers context for the 'context' object (pack, tool, vertical). This is complete for an agent to correctly 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the claim_token parameter in context ('pass it back later as pipeworx_feedback(...) to read whether it was fixed'), and by giving guidance on message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('Tell') and resource ('Pipeworx team'), and explicitly distinguishes from sibling tools like ask_pipeworx by framing it as feedback rather than a question. The use cases (bug, feature, data_gap, praise) are enumerated.

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 the tool ('Use when a tool returns wrong/stale data', 'when a tool you wish existed isn't in the catalog', 'when something worked surprisingly well') and when not to use it ('if the tool came from a different MCP server... file it with that server instead'). It also provides a clarifying note for identifying Pipeworx tool names.

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

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

The description adds significant behavioral context beyond the annotations: it discloses the data source (CF analytics-engine), states that no PII is included, describes the output shape (pack, tool, count), and notes caching behavior (5min-1h depending on window). This is rich, non-redundant transparency.

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

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

The description is front-loaded with a clear one-sentence summary, followed by a list of use cases, then technical notes. Every sentence earns its place; there is no repetition of schema or annotations.

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

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

The tool is simple (one optional parameter), and the description fully covers its purpose, usage, output shape, data source, and caching. Even without an output schema, the agent has enough information to invoke the tool and interpret results.

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

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

The schema already contains 100% parameter coverage, including an enum and a description explaining '24h (default) | 7d | 30d' and the trade-off between hot and steady-state demand. The tool description adds no additional semantic detail about the window parameter, so a 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 ('Returns') and names the resource ('top tools, top packs, and total call volume over a recent window'), clearly distinguishing it from sibling tools like discover_tools. The three enumerated use cases further reinforce what the tool accomplishes.

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 (discovering hot data sources, confirming canonical choices, aligning with agent needs) and explains window semantics (shorter vs. longer windows). However, it does not explicitly name alternative tools or state when not to use it, so it stops short of a full 5.

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

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

Even though annotations already indicate readOnlyHint, openWorldHint, etc., the description adds deep behavioral context: how the partition check works (>3pp deviations trigger signals), placeholder filtering, Jaccard similarity >=0.30, and the critical fill check with live CLOB depth. This goes far beyond the annotations and clarifies exactly what the tool computes and the caveat about book depth.

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

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

The description is long but well-structured, with clear sections for modes, semantic anchor, partition filter, response, and fill check. It front-loads the core purpose. Every major behavior is covered, though the density might be overwhelming for quick reading; it earns its length given the tool's complexity.

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

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

For a complex tool with no output schema, the description fully explains the response structure (opportunities[], partition_check, fill_check) and the interpretation of results (when to trade, when not). It also provides domain context (monotonicity, partition sums, Jaccard) and covers edge cases, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. However, the description adds meaningful detail beyond the schema: it explains that 'event' takes a slug or URL, 'topic' takes a seed question, and no args runs a trending scan. It also clarifies the difference in behavior between event and topic, which helps the agent pick the right 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 immediately states the tool's purpose: "Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks." It clearly distinguishes between 'event' and 'topic' modes and even mentions the no-argument trending scan, differentiated from all 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?

Explicit usage guidance is provided: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)' with concrete examples. It also tells the agent when not to trade via the fill check (realizable_edge_pp ≤ 0) and points to polymarket_fill_risk for custom sizing, showing awareness of 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?

Despite annotations already indicating safe read-only/idempotent behavior, the description adds substantial caveats: the 24h-move warning ('your edge may already be in the price'), the unreliable Fed signal rationale, slippage assumptions, and cache behavior (1h KV-level). It also discloses that partition arbs return kelly_fraction_half=0 by design.

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

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

The description is dense and front-loaded with purpose, but it is long (over 700 words) and requires careful parsing. It is structured with labeled sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) that help navigation, but some details could be streamlined without losing critical 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?

With no output schema and 9 parameters, the description carries a heavy burden and meets it: it enumerates the response top-level keys, per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), diagnostics funnel counters, caching policy, and filtering semantics. It also covers edge cases (placeholder-slug filters, >20% placeholder fraction skip, gates).

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; however, the description goes beyond schema by explaining the purpose of each knob group (tradeable-edge filters, min_partition_leg_kelly) and the rationale for defaults. This adds contextual value beyond the parameter 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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It explicitly frames the tool as built for 'what should I bet on today' and distinguishes itself from sibling tools by aggregating opportunities across segments rather than paging hundreds of markets.

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

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

It states the core use case ('agents discover opportunities without paging hundreds of markets') and provides extensive knob guidance (e.g., 'Set to 2 to require tight books') with rationale. It does not explicitly name alternative sibling tools, but it clearly implies when to use this tool for discovery vs. deeper analysis.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds substantial context: 60-day snapshot TTL, gaps caused by cache-miss days, decay computed from daily closes of edge_pp_net, and the signed meaning of edge_pp_net (negative = SELL YES). It also explains the historical depth limitation. This goes well beyond the annotation hints.

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

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

The description is long but intentionally structured into purpose, args, RESPONSE, and LIMITS sections. Each sentence carries information, though some phrasing (e.g., 'the latter is wide for a reason nobody is willing to take') is illustrative but not essential. It is well front-loaded with the core question it answers.

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 the return structure: tracked[], expired[], and snapshot_dates[], including fields like trend, decay_pp_per_day, lifespan_days, and edge_pp_net. It also covers data gaps, TTL, and computational basis. For a telemetry tool, this is complete and actionable for an agent.

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

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

Schema coverage is 100% for both parameters, so the description need not restate them. The description adds useful semantic context: window is described as a 'snapshot family' and days as a lookback with default/max values. It also connects the response fields to the parameter behavior (e.g., 'snapshot_dates[] = which days actually have data'). This adds value beyond the schema.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?' It uses a specific verb+resource and distinguishes itself from sibling polymarket_edges by focusing on historical persistence rather than 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 implies when to use it: for understanding edge longevity and decay, contrasting 'a fresh wide edge and a 3-week-old wide edge.' It does not explicitly name alternatives or exclusion criteria, but the context is clear enough for an agent to select this tool for temporal edge analysis.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses the tool's behavior in detail: it walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, verdict), and explains partial basket fill risks. This adds substantial context not present in the structured annotations, and it is fully consistent with them.

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

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

The description is long but logically structured into single-market and basket sections, with each sentence adding substantive detail. It is front-loaded with the core purpose and required parameters. It could be slightly trimmed, but the density of information 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?

With no output schema, the description fully compensates by enumerating all return values for both modes, including theoretical_sum, realizable_sum, capture_ratio, thin_legs[], and forced_directional_risk. It also covers edge cases like partial fills and behavioral risks, making the tool's behavior predictable for the agent.

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

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

Although schema coverage is 100%, the description enriches parameter meaning significantly. It clarifies that `size_usd` is interpreted as 'max spend on buys, target proceeds on sells' in single-market mode, while in basket mode it is 'settlement notional — shares per leg.' It also explains the dual meaning of `side` and the auto-default behavior. This goes well beyond the basic schema descriptions.

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

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

The description clearly states the tool's function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket/partition modes, and the specificity ('walks the ladder', returns verdicts) differentiates it from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than opportunity detection.

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

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

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 directional risk) and names the alternative tools.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds extensive behavioral context beyond annotations: compatibility_warning triggers, temporal_alignment semantics, skipped_cross_type/subtype counters, and the note that most pre-mapped topics return warnings. No contradictions exist between description and annotations.

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

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

The description is long but highly structured and dense with unique information: modes, response fields, safety signals, and caveats. Every section earns its place, but it could be slightly trimmed for readability without losing value. Still, the complexity of the tool 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?

This is a complex tool with no output schema, yet the description fully explains the response structure (leg-by-leg prices, matched spread, top_spreads_pp), the safety fields (compatibility_warning, temporal_alignment), and the meaning of skipped_cross_type/subtype. It also covers edge cases like unmatched pairs and temporal mismatches, making it complete for agents to invoke and interpret results.

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

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

Schema coverage is 100% with each parameter described, so baseline is 3. The description adds valuable semantics by explaining how the three parameters interact: 'topic' auto-fetches from shortcuts, and the explicit ticker/slug parameters override the mapped side. This goes beyond the schema's per-parameter descriptions, though it does not delve into details like exact ticker formatting.

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+resource statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes this from sibling tools like polymarket_arbitrage by focusing specifically on cross-venue comparison rather than single-venue arbitrage, and its title reinforces the purpose.

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

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

The description explicitly defines two usage modes (topic and explicit pairings) and explains when results are meaningful vs. not ('when the bet shapes are equivalent that delta is a real signal, when they aren't the tool says so'). It also warns that 'pre-mapped ≠ tradeable,' giving clear when-not guidance, though it does not name alternative tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it is scoped to the caller's identifier (anonymous IP, BYO key hash, or account ID), and omitting the key returns a list of all keys. This goes beyond the annotations without contradicting them, though it doesn't specify the return format for a missing key, which slightly drops the score.

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 long and front-loaded with the primary action. Every clause adds value: the retrieval behavior, the list-all option, the use case, the scoping note, and the pointers to related tools. No filler or redundancy.

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

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

Given the tool's simplicity (one optional parameter, no output schema) and rich annotations, the description covers all essential aspects: what the tool does, when to use it, how it behaves (listing vs. retrieval), scoping, and relationship to remember/forget. It is complete enough for an agent to select and invoke the tool correctly without ambiguity.

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

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

The input schema has 100% coverage with a clear description for the single 'key' parameter, so the baseline is 3. The description adds meaningful context beyond the schema by explaining that keys are 'previously saved via remember' and providing examples of key values (target ticker, address, notes), plus clarifying that omitting the key lists all saved keys. This enriches the parameter semantics beyond a bare schema definition.

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: 'Retrieve a value previously saved via remember, or list all saved keys'. It clearly distinguishes from siblings by mentioning 'remember' and 'forget' and provides concrete examples like the user's target ticker or prior research notes, making the tool's purpose 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 explicitly says to use this tool 'to look up context the agent stored earlier' and contrasts it with alternatives: 'Pair with remember to save, forget to delete.' This gives the agent a clear decision rule for when to invoke this tool versus related ones, and it even notes the optional key argument for listing all keys.

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 'Set mark_read:true to flag returned events read', revealing a state-changing side effect. This contradicts the annotation readOnlyHint: true, which implies the tool has no side effects. The description also implies idempotency is broken when mark_read is true, conflicting with idempotentHint: true. Per the rubric, a contradiction with annotations forces a score of 1.

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

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

The description is four sentences long, front-loaded with the core purpose, and each sentence adds distinct value: return fields, filters, read flag behavior, and polling/alternative URL. There is no redundancy or fluff.

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

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

With no output schema, the description covers the key return fields (source, citation_uri, raw payload), filtering options, the mark_read side effect, and even mentions the alternative HTTP endpoint. For a read-oriented tool with five optional parameters, this is comprehensive.

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 baseline is 3. The description adds value by giving an example for type ('sec_8k') and explaining the consequence of mark_read ('the next call only shows newer ones'), going beyond the schema's basic descriptions.

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

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

The description opens with 'Pull fired events from your subscription feed', using a specific verb and resource. It clearly differentiates from siblings like recent_changes by specifying 'alerts the evaluator has written to your persisted feed', leaving no ambiguity about the tool's purpose.

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

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

The description provides clear usage context: filtering by type and since, setting mark_read, and polling. It also mentions an alternative endpoint for scripts/dashboards, but does not explicitly state when not to use this tool versus alternatives, 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?

Beyond annotations (readOnly, idempotent, openWorld), the description discloses the fan-out architecture, GDELT→GNews fallback behavior, USPTO PatentsView sunset soft-fail, `since` relative/ISO syntax, and the return shape with citation URIs. No contradictions with annotations; all behavior is consistent with non-destructive, idempotent reads.

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

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

Although long, the description packs high-density, essential information and is front-loaded with user-intent examples. Each clause covers a distinct aspect (sources, fallback, parameters, output, alternative tool), so there is little waste.

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 specifying the return structure (changes[] grouped by source, total_changes, pipeworx:// URIs) and the soft-fail behavior. Given the multi-source complexity, it is sufficiently complete for an agent to decide and invoke correctly.

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

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

Schema already documents all three params, so baseline is 3. Description adds value by detailing `since` formats and offering '30d' or '1m' as typical monitoring defaults, plus clarifying value as ticker or CIK.

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 leads with concrete user-intent phrases and defines the tool as a change feed for a company over a time window, naming the three upstream sources. It explicitly distinguishes itself from entity_profile and implies a different scope than sibling research tools.

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

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

It provides natural-language triggers like 'What's new with X' and 'updates on Acme', and states it fans out to SEC, news, and patents in one parallel call. It explicitly tells when to prefer entity_profile for static profiles regardless of window, giving a clear alternative.

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 valuable behavioral context beyond the annotations, including storage scoping by identifier, persistence differences between authenticated users and anonymous sessions (24 hours), and pairing with recall/forget. It does not contradict the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false).

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

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

Three sentences, each serving a distinct purpose: state what it does, provide usage guidelines with examples, and give storage/persistence details. No filler or repetition. 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 the tool's simplicity, the description fully covers purpose, usage timing, behavioral specifics (persistence, scoping), and how it relates to sibling tools. No output schema exists, but return values are not critical for a save operation, and annotations cover idempotency and safety.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra semantic meaning by explaining the key-value pair structure is scoped by the identifier and providing example keys ('resolved ticker', 'target address'), which goes slightly beyond the schema descriptions.

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

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

The description uses a specific verb and resource ('Save data the agent will need to reuse later') and clearly distinguishes itself from sibling tools by naming recall and forget for complementary operations. It also provides concrete examples (ticker, address, preference) that make the purpose immediately understandable.

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

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

The description gives explicit 'when to use' guidance with examples ('Use when you discover something worth carrying forward...') and mentions alternatives for related actions ('Pair with recall to retrieve later, forget to delete'). However, it does not explicitly state when not to use this tool, which would elevate it to 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds substantial behavioral context: it cascades through multiple lookup endpoints, auto-disambiguates input, returns specific fields (ticker, CIK, RxCUI, brand), and provides citation URIs. This enriches the agent's understanding of what the tool does internally and what to expect.

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

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

The description is well-structured with a clear opening (natural language examples), a concise purpose statement, and a detailed breakdown of supported types. It is longer than a minimal description but every sentence adds value, and the front-loaded purpose ensures critical information is immediately visible. Minor redundancy in repeating supported types could be trimmed, but overall it is well-organized.

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

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

Despite lacking an output schema, the description thoroughly explains return values for each entity type (ticker, CIK, company_name, citation URI for companies; RxCUI, ingredient, brand for drugs). It also explains the cascading lookup behavior and that it replaces manual lookups. For a tool of moderate complexity with two parameters, this is complete enough for correct usage.

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

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

The schema already provides full coverage for both parameters (100%), including examples and input formats. The description reinforces this with additional context about the returned values and how the input types map to output types (e.g., company returns CIK, drug returns RxCUI). While it doesn't add new syntax details, it meaningfully elaborates on the implications of each parameter choice.

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 with a specific verb ('resolve') and resource ('user-spoken NAME to the canonical/official identifier'). It distinguishes itself from siblings by emphasizing it should be used FIRST when needing an ID, and it enumerates supported entity types (company, drug) with concrete examples (ticker, CIK, RxCUI).

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 FIRST whenever you have a name but need an ID.' It also notes efficiency ('replaces 2-3 manual lookups'). However, it does not explicitly state when NOT to use this tool (e.g., if an ID is already known) or mention alternative tools for specific contexts, though the directive is clear enough.

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

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

The description adds behavioral context beyond the annotations: it explains that the tool 'Probes each entity with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and details the return fields ('score, confidence, signal density per entity'). This is useful information not captured by the readOnlyHint, idempotentHint, or destructiveHint annotations.

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

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

The description is three sentences long, front-loaded with the primary purpose, then details the process and use case. Every sentence earns its place: the first states the core operation, the second explains the mechanism and output, the third gives a concrete example. There is no redundancy or extraneous information.

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

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

With no output schema, the description appropriately explains the return format: 'ranked list with score, confidence, signal density per entity.' It also references the sibling tool ai_visibility_check, providing context about the underlying probes. It does not mention the optional models parameter or potential wait times, but those are documented in the schema, so the description is sufficiently complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds no substantial meaning for parameters like models or _apiKey; it only echoes the entities concept ('your brand + N competitors'), which the schema already covers with the 'First entry treated as the subject' note. This aligns with the baseline of 3 when the schema carries the parameter documentation burden.

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: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare), resource (AI visibility), and scope (multiple entities). It distinguishes itself from siblings by mentioning it probes each entity with ai_visibility_check and ranks results, which differentiates it from single-entity tools and generic compare 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 a clear use case: 'Useful for competitive AI-marketing audits' with an example query. This tells the agent when to use the tool. However, it does not explicitly mention alternatives or exclusions, such as 'for a single entity, use ai_visibility_check directly.' The context is clear but no when-not-to-use guidance is given.

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 details: partial failure degradation, bundlephobia's first measurement can take 5-30s, and sources_failed field. No contradiction with annotations.

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

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

Though long, every sentence adds distinct information: composite nature, usage cues, return fields, ecosystem limitations, and failure timing. It is front-loaded with the core purpose 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?

Without an output schema, the description thoroughly enumerates the return structure (summary block fields, per-advisory detail, links, recent versions) and failure semantics. This is sufficient for an agent to understand expected outputs and edge cases, even for a multi-source 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 covers both parameters with descriptions (100% coverage), so baseline is 3. The description reinforces 'version defaults to latest' and scoped package acceptance, but adds little new parameter syntax beyond what the schema already provides.

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

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

The description clearly states the tool's verb ('check') and resource ('npm package'), framing it as a composite check across deps.dev and bundlephobia. It differentiates from sibling tools like scan_competitor_ai_presence by focusing on package health/cost analysis.

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

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

Explicitly instructs 'Use whenever an agent asks is X safe / popular / small' with concrete example. Also gives an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', which guides the agent to alternatives for non-npm packages.

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

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

Despite readOnlyHint=true and destructiveHint=false, the description adds critical behavioral detail: text is split into 500-char overlapping windows, uses BGE-base-en embeddings and cosine similarity, has a 200K char cap with truncation flagged, and every passage includes offsets. This goes well beyond annotations and discloses potential edge cases (truncation) and retrieval mechanics.

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

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

The description is well-structured with a clear opening sentence, usage context, technical details, and a pairing note. All sentences earn their place, no fluff. It's moderately sized but information-dense, front-loaded with purpose and then specifics.

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 what the agent receives (passages with offsets and similarity scores), the algorithm, limits, and truncation behavior. It covers the full scope: purpose, use case, mechanics, edge cases, and integration with siblings. Given the tool's moderate complexity, it is complete.

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

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

Schema coverage is 100%, so the schema already describes all three params. The description adds value by explaining the query parameter with concrete examples and clarifying the 'text' param as the fetched record content. However, it doesn't add much detail about 'limit' beyond the schema, but the examples and cap context are helpful. Baseline 3, plus extra value from examples and integration context.

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

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

The description clearly states it performs semantic search inside a fetched record (e.g., SEC filing, article) using a natural-language query, returning top-N passages with offsets and scores. It explicitly distinguishes itself from siblings by pairing with ask_pipeworx_grounded and emphasizing its in-place search role, making it unique among tools like ask_pipeworx or deep_research.

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

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

The description gives explicit use cases: when the record is too big to fit in the prompt, to save context, and to verify quotes via offsets. It also mentions pairing with ask_pipeworx_grounded, providing a clear alternative workflow. It does not explicitly say when not to use it, but the context is strong enough.

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

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

The description adds meaningful behavioral context beyond the annotations: it notes that anonymous/BYO accounts cannot persist subscriptions, that the tool returns a new subscription id, and that SMS has a 10/day cap with phone verification. These are valuable operational details not present in the annotations, and no contradiction 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 dense but well-structured, starting with the core purpose, then account requirements, supported types, and delivery channels. While it is longer than minimal, every sentence contributes useful information, and the structure aids readability.

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 is comprehensive for the types it covers, but it lists only three of the five supported types (sec_8k, polymarket_edge, fred_series), omitting patent_grant and clinical_trial that appear in the schema. This could mislead an agent into thinking only three types exist. The missing return format (beyond id) and lack of error scenarios are minor gaps given the schema coverage.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds extra semantic meaning by providing concrete examples like 'items:["5.02"] = officer change' for sec_8k and explaining delivery channel options. This goes beyond the schema's bare parameter descriptions and aids correct parameter construction.

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: 'Create a proactive monitoring subscription to a live-data event stream,' clearly stating what the tool does and distinguishing it from sibling tools like list_subscriptions and unsubscribe. It also details supported subscription types and delivery channels, reinforcing the tool's purpose.

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

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

The description provides clear context: it states the account prerequisite (OAuth required), explains how to retrieve the always-on feed via recent_alerts or the registry URL, and notes SMS delivery constraints. However, it does not explicitly contrast with alternatives like list_subscriptions or unsubscribe, so the guidance is good but not fully exclusionary.

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

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

Annotations already declare the tool safe (readOnly, openWorld, idempotent, non-destructive). The description adds value by explaining the output structure (category-bucketed example questions with tool + argument shape) and the dynamic nature (live catalog). It does not introduce any behavioral contradictions, but also doesn't disclose potential subtleties like token limits or performance.

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

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

The description is a single paragraph around 100 words, front-loaded with example questions and followed by behavior and usage. It is reasonably concise, though the category list is repeated from the schema, making it slightly redundant. Still, every sentence contributes to understanding the tool's purpose and output.

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 sufficiently explains return value (category-bucketed example questions with exact tool and argument shape), the optional parameter, and the primary use case. The tool is simple with one optional parameter, and the description covers all necessary aspects, making it complete for an agent to select and invoke correctly.

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

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

The schema describes the topic parameter with categories and the omit behavior; the description repeats this exactly without adding new syntax, format, or example values. Since schema coverage is 100%, the description provides no additional semantic meaning, so the 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 identifies the tool as the onboarding entry point for an agent to discover what it can ask, using explicit verbs like 'Returns category-bucketed example questions' and specifying the exact categories. It distinguishes from siblings by naming the use case ('Use this FIRST when you do not yet know what Pipeworx can do for you') and listing the meta-tools it teaches.

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

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

Provides explicit guidance on 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') and how to invoke with optional topic. However, it does not explicitly mention alternatives or when not to use this tool, such as comparing with discover_tools, so it misses the full 'when-not' aspect.

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=false, idempotent=true, destructive=false), the description adds crucial behavior: ownership enforcement ('you can only cancel your own subscriptions') and the fact that the row is deactivated, not deleted, so historical events remain available via recent_alerts. This significantly enriches the agent's understanding without contradicting annotations.

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

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

The description is two sentences, front-loaded with the purpose ('Cancel a subscription by id') and immediately followed by affect. Every sentence earns its place, with zero waste.

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 tool with rich annotations, the description covers everything needed: the action, the ownership constraint, the soft-delete effect, and the path to historical data. No output schema is needed, and the context is fully 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 the only parameter ('id') as 'Subscription id (uuid) returned by subscribe' with 100% coverage. The description adds only that the tool cancels 'by id', which doesn't provide 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 clearly states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by explicitly describing the cancellation action and the id parameter.

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

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

Provides clear context for when to use: you cancel a subscription by id, and ownership is enforced (only your own). It also points to an alternative for historical access via 'recent_alerts'. However, it doesn't explicitly exclude alternatives or name them as 'use X instead', so it stops short of full guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive, and open-world. The description adds rich behavioral context: percent-delta math for financial claims, fallback to grounded pipeline, return values (verdict types, citation, reasoning), and the tolerance override semantics. 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 longer than minimal but each sentence contributes: trigger phrases, routing logic, output contract, and efficiency claim. It is well-structured and front-loads the use case, though it could trim some redundancy.

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

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

Given no output schema, the description sufficiently explains return values (verdicts, actual value, citation, reasoning) and handles both financial and non-financial paths. It covers edge behavior (fallback, tolerance).

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 already describes both parameters at 100% coverage, giving baseline 3. The description adds guidance on tolerance_pct (set 1–2 for hallucination detection) and clarifies default cap at 5%, plus examples that illustrate claim format.

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

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

The description clearly states the tool verifies natural-language factual claims against authoritative sources, with explicit examples of query phrasing ('Is it true that…', 'fact check'). It distinguishes its scope by splitting company-financial claims (SEC EDGAR) from other factual claims, setting it apart from sibling research or look-up 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides routing guidance for financial vs. non-financial claims and notes it replaces 4–6 sequential calls, implying it's the preferred single-call alternative.

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