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?

Beyond the annotations, the description reveals routing behavior, argument filling, verified sources, and the stable pipeworx:// citation URI format in the response. It also clarifies scope (current/historical structured data) and that web-searchable questions are still appropriate. No contradiction with the readOnly/openWorld/idempotent hints.

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

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

The description is long but front-loaded with the key routing/citation behavior and uses examples efficiently. There is minor redundancy around preferring over web search ('PREFER OVER WEB SEARCH' and 'even if web search could also answer it'), but this is acceptable for emphasis.

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 broad router with no output schema, the description covers input format, accepted domains, when to invoke it, and what the return looks like (structured answer with citations). The only notable gap is differentiating from sibling ask_pipeworx variants, which matters more to sibling-selection than to invoking this tool correctly.

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

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

The schema already documents all six parameters at 100% coverage, so the description only needs to add usage color. It does so with trigger phrases, query types, and concrete examples like 'current US unemployment rate' and 'Apple's latest 10-K'. This meaningfully helps an agent form a valid natural-language question even though the schema alone is sufficient.

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

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

The description states the tool's job precisely: it routes natural-language questions to one of 5,798 tools across 1,517 verified sources, fills arguments, and returns cited structured answers. It also gives concrete examples and identifies the factual-data niche. However, it does not differentiate itself from close siblings like ask_pipeworx_beta or ask_pipeworx_grounded, so it stops short of full sibling differentiation.

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

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

The description explicitly tells agents to prefer this tool over web search for factual questions, lists trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and supplies six representative examples. It lacks a clear 'when not to use' section beyond implied coverage of live news, and it does not address sibling alternatives.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context beyond those: candidate routing improvements are enabled live when under test, none is active right now, and this is a full working router rather than a fallback. It also clarifies that it currently matches ask_pipeworx exactly, which is useful for calibrating expectations.

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 moderately long but every sentence earns its place: identity, current experimental status, usage instruction, and clarification that it is a functional router. It front-loads the key identity ('Beta version of ask_pipeworx') before providing context. Minor redundancy exists in the last clause, but nothing is wasted.

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

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

Compared to the high similarity with ask_pipeworx and the complexity of a 6-parameter router, the description covers the essential context: what it does, how it relates to the stable router, whether a candidate is active, and how results are used. It does not describe the exact response shape, but it references the same response shape as ask_pipeworx, and the schema covers parameter details. The frequent update about active candidates is a helpful touch.

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 input schema already documents the parameters (including q, text, input aliases). The description adds the useful note that arguments are identical to ask_pipeworx, but it does not elaborate on parameter meaning or behavior. Since the schema carries the burden, 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 states a specific verb and resource: it is the beta version of ask_pipeworx, a universal router covering the same 5,798 tools, arguments, and response shape. It clearly differentiates itself from the stable ask_pipeworx by noting it carries experimental routing improvements, and it even specifies the current state (no active candidate), so an agent can tell it apart from siblings without consulting schemas.

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

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

It explicitly instructs the agent to use it exactly like ask_pipeworx when wanting the newest routing, and explains that results are compared against the stable router to decide merges. It does not include an explicit 'do not use when...' clause, but the beta-vs-stable contrast and the statement that no candidate is active make the selection 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?

Annotations already declare readOnly, idempotent, and non-destructive behavior; the description adds valuable context beyond this: the explicit refusal contract, refusal reasons, the grounding guarantee, and 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?

Front-loaded with the core purpose, then flows logically through behavior, return shape, usage guidance, and cost. Every sentence adds distinct information and there is no filler or repetition.

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

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

Despite having no output schema, the description fully documents the return contract, refusal behavior, and success fields. It covers routing, grounding behavior, usage contexts, and alternatives, 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?

Schema description coverage is 100%, so the schema already fully documents the question parameter and its aliases. The description adds no parameter-specific meaning, but also doesn't need to — the baseline of 3 applies.

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

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

States a specific verb and resource: a hallucination-resistant answer mode for high-stakes reads that extracts answers only from tool results. It also distinguishes itself from ask_pipeworx by naming the sibling and the key behavioral difference.

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

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

Explicitly says when to use it — when the answer will be quoted, cited, or acted on and facts must not be invented — and when to avoid it by preferring ask_pipeworx for casual lookups. It also gives concrete examples like financial verdicts, legal claims, medical lookups, and public statements.

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?

Even with strong read-only/idempotent annotations, the description adds substantial behavioral context: findings packet structure, citation_uri fetchability, explicit gaps[], contradictions[], semantic excerpting of long records, latency expectations, and never-invented guarantees. No contradiction with annotations; the NOT-open-web-search statement is consistent with using structured sources.

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 auth requirements and the sibling fallback, but it is long and structurally messy: the '(Second iteration: ...)' passage reads like an artifact and overlaps with schema content about depth. Every piece of information is useful, but the organization hurts 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?

Despite having no output schema, the description explains the return packet's key fields, citation semantics, gaps, contradictions, latency, auth, and plan constraints. For a complex tool, this is enough for an agent to know when to call it and what to expect back.

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 has 100% parameter coverage, providing the baseline of 3. The description adds meaningful extras beyond the schema: thorough requires a paid plan, depth tiers map to additional passes, and expected latency varies by depth. It does not need to re-explain the question parameter since the schema already handles it.

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 names the verb and resource: it performs grounded multi-source research across Pipeworx's 1517 structured data sources in one call. It actively differentiates itself from siblings by saying it is NOT open-web search and by contrasting with ask_pipeworx for single lookups. The purpose is 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?

Usage guidance is unusually explicit: use ask_pipeworx if not signed in or for a single lookup, use deep_research for broad/multi-part questions over structured data, and thorough depth requires a paid plan. This gives an agent clear routing rules with named alternatives and conditions.

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?

The description goes far beyond the readOnly/openWorld/idempotent annotations by detailing fan-out behavior, which sources are consulted, soft-failure of USPTO patent data, and the meaning of empty sections as real no-data results. It also discloses the resolved:false response for private companies, which is important behavioral context.

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

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

The description is dense and front-loaded with examples and the ALWAYS PREFER directive, and the output sections are carefully organized. It is long, but most sentences carry functional information; only slight repetition of the type/value schema notes keeps it from being maximally concise.

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 present, the description carries the full burden of explaining return values. It enumerates every major response section, its data source, expected empty behavior, and failure semantics, making the tool safely invocable in nearly all expected scenarios.

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 documents both parameters. The description adds value by clarifying that type is interchangeable, showing a zero-padded CIK format, and explaining resolved_from/resolved_to when a name is provided, but it partially repeats existing schema notes.

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

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

The description opens with concrete user phrasings like "Tell me about X" and defines the tool as a "full cross-source profile of a US public company in ONE parallel call." It clearly distinguishes itself from single-pack SEC/XBRL/news lookups by framing the tool as the preferred holistic alternative.

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

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

It explicitly says to "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups" when the user asks for a holistic view, and specifies the accepted input forms and the private-company behavior. This gives an agent a clear selection rule relative to narrower lookups.

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

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

Annotations already declare readOnlyHint=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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already establish this as a safe read operation, and the description adds substantial behavior beyond that: legs with 'unknown' metric_type/match_subtype are NEVER paired, compatibility_warning can be non-empty even with matched_pairs>0, temporal_alignment null means 'could not be computed, not that the two sides align,' spreads are gross (fees not modeled), and skipped_cross_type/subtype counters expose dropped comparisons. This richly discloses match mechanics and failure modes with no contradiction of 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?

At roughly 330 words, this is dense and internally labeled (TWO MODES, RESPONSE, SAFETY FIELDS), but the structure is essentially paragraphs — the machine-readable compatibility codes are explained as running prose, and the single most important operational caveat ('pre-mapped ≠ tradeable') is buried at the very end. Phrasings like 'NOT the same as confirmed-aligned' add parsing load. Every sentence carries information, but the density and back-loaded caveat keep it from being a model of concision.

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

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

Despite having no output schema, the description fully inventories the return contract: leg-by-leg raw probabilities, top_spreads_pp with per-entry flags[], skipped_unclassified, low_confidence_pairs[], temporal_alignment fields, fees_note, and the two skipped counters. For a tool with 3 optional params, two modes, and a rich result shape, nothing an agent needs to invoke it or interpret results is missing.

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

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

Schema coverage is 100% and each parameter already carries a description, so baseline is 3. The description adds genuine inter-parameter semantics beyond the schema: the topic-vs-explicit mode distinction, the 'BOTH modes run the identical token-overlap matcher' equivalence, and the override relationship between topic and the two explicit fields. It does not add format-level detail, but the mode logic is a meaningful increment.

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

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

The opening sentence names a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' The 'cross-venue' scope clearly separates it from the Polymarket-only sibling tools (polymarket_edges, polymarket_arbitrage, polymarket_fill_risk), which none of the other tools in the sibling list combine with Kalshi. An agent can tell what this tool uniquely 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 TWO MODES section gives explicit when-to-use guidance: pre-mapped topic shortcuts vs explicit ticker/slug for custom pairings, and states that both modes run the identical matcher. It also sets expectations with 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' However, it never names alternative sibling tools or states when NOT to use this tool in favor of them, so it stops one step short of a 5.

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

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

Annotations already declare readOnlyHint=true, 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 readOnly/openWorld/idempotent annotations, the description discloses significant behavioral nuance: ambiguity is handled by returning figi_candidates rather than asserting a match, unresolved identifiers are explicitly listed rather than omitted, LEI/FIGI enrichment degrades gracefully, and each call internally cascades through several lookup endpoints. This is far more transparency than the annotations alone provide.

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

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

The description is long but information-dense, front-loaded with example queries and the 'Use FIRST' directive. The extended parentheticals are verbose, yet nearly every clause adds needed operational detail, so the length is justified even if a tighter rewrite could improve skimmability.

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 two-parameter tool with no output schema, the description fully covers what to expect back: source-labelled identifiers, unresolved fields, figi_candidates on ambiguity, RxCUI/ingredient/brand for drugs, and graceful degradation behavior. An agent has enough context to call it correctly and interpret results confidently.

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

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

Although schema coverage is 100%, the description adds high-value guidance that the schema lacks: pass only the entity name, not the full noun phrase; for bonds use the issuer exactly as printed; trailing security-class words will fail; and accepted input forms include ticker, CIK, ISIN, or name. These pitfalls and examples materially improve correct invocation.

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

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

The description opens with concrete example queries and a crisp statement: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It names the resource (entities), the action (resolve names to identifiers), and covers both supported types, which clearly differentiates it from sibling tools like entity_profile 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?

It explicitly says 'Use FIRST whenever you have a name but need an ID,' and gives many example phrasings. It does not explicitly contrast itself with sibling tools like entity_profile or compare_entities, but the 'use first when you need an ID' guidance is clear enough to route an agent correctly.

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?

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses subtle behavioral distinctions: could_not_verify means the check did not happen and must not be treated as evidence, while unsupported means no source covers it. It also documents the routing logic (structured EDGAR vs grounded pipeline) and the inclusion of verbatim evidence with citations. This goes well beyond the annotations.

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

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

The description is dense but well-structured: trigger phrases, usage guidance, routing, return contract, and error semantics. No filler sentences; every clause serves a purpose, and the length is justified by the tool's complexity. It is front-loaded with examples and clearly 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 having no output schema, the description fully specifies the return contract (verdict values, actual value with citation, reasoning) and edge cases. It covers when to use, internal routing, and replaces-multi-call efficiency, making it self-sufficient for an agent to select and safely invoke. The context signals (2 params, no output schema) are well compensated by the description.

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

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

Schema coverage is 100% and both parameters are fully described in the schema. The description does not add parameter-specific semantics beyond the schema; it mentions tolerance only in passing in the context of hallucination detection, which is already present in the schema's tolerance_pct description. Baseline 3 is appropriate when the schema carries the 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 opens with multiple natural-language trigger phrases ('fact check', 'verify the claim that…') and explicitly states the tool's function: natural-language claim verification against authoritative sources. It differentiates from siblings by specifying the two verification pathways (SEC EDGAR + XBRL vs grounded pipeline) and the returned verdict types, making the 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?

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear invocation context. It doesn't name alternative tools or exclusions, but the 'Replaces 4–6 sequential calls' note conveys its role as a consolidated, purpose-built tool, so the usage context is clear though not exhaustive.

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