disify

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

Annotations already indicate safe read-only, idempotent, non-destructive behavior. The description adds valuable context beyond annotations: the default model (Workers AI Llama-3.3-70b, free), API key requirements for Anthropic with direct billing implications, and the return structure. These details help the agent anticipate costs and setup 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 three well-structured sentences. It front-loads the core purpose, then adds operational details (default model, API key, returns), and concludes with use cases. Every sentence contributes new information with 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?

Despite no output schema, the description explains return values per-model and combined. It covers default behavior, optional API key, cost implications, and use cases. Minor gaps remain around error handling (e.g., invalid key) and rate limits, but for a simple read-only probe tool, the description is sufficiently complete.

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

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

Schema coverage is 100% (all 4 parameters have descriptions), so baseline is 3. The description repeats some schema info (e.g., default model, _apiKey requirement) and adds cost context ('you pay Anthropic directly'), but it does not add significant parameter-level semantics beyond what the schema already provides. The return structure is helpful but relates to output, not parameters.

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

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

The description clearly states the tool's function: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This is a specific verb+resource combination (probe LLMs, score visibility) that distinguishes it from siblings like scan_competitor_ai_presence by focusing on per-model scoring and combined views.

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: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly mention alternatives or when not to use, but it clearly implies suitable scenarios. This meets the 'clear context, no exclusions' level.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond that: it routes to internal tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and is described as a single fast call. This goes beyond the annotations without contradicting them.

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

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

The description is longer than average, but every sentence earns its place: positioning, mechanism, trigger phrases, examples, escalation paths, and edge cases. It is front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and uses examples efficiently to clarify scope.

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 routing tool with no output schema, the description is remarkably complete. It explains what the tool does, when to use it, what to expect in the response (structured answer with citations), and how it compares to the most relevant siblings. An agent has everything it needs 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 description coverage is 100%, so the schema already fully documents the 'question' parameter and its aliases. The description reinforces with realistic example queries, but it does not add new parameter-level semantics beyond what the schema provides. 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 opens with 'PREFER OVER WEB SEARCH' and states the precise role: route factual questions to one of 5,724 tools across 1,497 verified sources, fill arguments, and return structured answers with citation URIs. It clearly differentiates itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point.

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

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

The description explicitly tells when to use it ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), when to prefer it over web search, and when to escalate to ask_pipeworx_grounded or deep_research. It even covers breaking-news cases, making the usage decision unambiguous.

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

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

The description adds substantial behavioral context beyond the read-only, open-world, idempotent annotations: candidate routing improvements are enabled live when under test, none is currently active, and the tool is a full working router rather than a fallback stub. This transparently sets expectations about experimental behavior.

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

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

The description is longer than average, but the details about candidate routing, inactive status, and comparison behavior all earn their place. It is front-loaded with the central purpose and uses the final sentence to dispel a likely misconception.

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

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

For a single-required-parameter router with rich annotations, the description covers operation, experimental status, and relationship to the stable version. The main gap is that it defers response details to 'same response shape' rather than describing the actual return format, especially since no output schema is provided.

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

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

Schema coverage is 100% and all six parameters are aliases for the same natural-language 'question' input, so the schema already carries the semantic meaning. The description only adds that arguments are identical to ask_pipeworx, which provides no new parameter-level detail beyond the schema.

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

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

The description clearly identifies the tool as a beta universal router with the same 5,724 tools, arguments, and response shape as ask_pipeworx, so an agent can understand what it does. It differentiates from the stable ask_pipeworx sibling by its experimental routing status, though it does not explicitly contrast with ask_pipeworx_grounded.

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

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

The description explicitly says to use it exactly like ask_pipeworx when the newest routing is wanted, and explains that results are compared to the stable router to decide merges. It implies when the stable version would be preferable but does not spell out exclusions.

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

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

Beyond the readOnly and idempotent annotations, the description discloses refusal behavior with an exact contract: success returns evidence and confidence, and failure returns one of five explicit refusal_reason values when data doesn't directly answer. It also states that it costs one extra LLM call, which annotates unobservable cost behavior.

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

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

The description is front-loaded with purpose and exception flow remains dense throughout. The source-count detail (5,724 tools across 1,497 sources) is not essential for invocation, but the rest of the content — routing, return shape, refusal reasons, use cases, and cost tradeoff — earns its place.

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

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

With no output schema present, the description fully specifies the success and failure return contracts, including the refusal_reason enum. It also covers the routing behavior, when to use it, and the cost tradeoff, so an agent has everything needed to invoke and interpret this tool correctly.

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

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

Schema description coverage is 100% and every parameter is already described as a natural-language question or alias. The tool description adds no parameter-level meaning beyond that, so the schema carries the burden and the baseline of 3 is appropriate.

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

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

The description opens with a specific, differentiating purpose: hallucination-resistant answer mode for high-stakes reads. It distinguishes itself from ask_pipeworx by explaining it routes the same way but then extracts the answer using only the tool result, so an agent can tell them apart.

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

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

It gives explicit when-to-use guidance: whenever the answer will be quoted, cited, or acted on and the agent must not invent facts, with concrete domains. It also tells the agent to prefer ask_pipeworx for casual lookups, naming the alternative and the condition that selects it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc., but the description goes far beyond them by detailing the resolver contract, low-confidence match short-circuiting, closed/dead market handling, wide-spread illiquidity warnings, and resolution-rule risk (e.g., refund_50_50). It clearly discloses what happens when matches are fuzzy and how news fallback works, giving the agent a rich behavioral model.

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 meticulously structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and every sentence conveys a distinct, valuable piece of information. It is front-loaded with the core purpose and then layers details logically, with no filler.

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

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

With no output schema, the description must explain return values and it does so extensively: result.market fields, result.analysis with edge calculations, result.evidence, resolver fields, parent_event, and news fallback fields. It also covers edge cases and safety mechanisms, making it exceptionally complete for a tool of this complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces the 'market' parameter by showing slug/URL/question text examples, and explains 'depth' and 'include_raw' implicitly through fan-out and response size notes. However, it does not add substantial new meaning beyond the schema's own parameter descriptions, so it earns the baseline.

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

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

The description opens with a clear, specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It goes on to state exact use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and distinguishes itself from sibling tools by focusing on bet-level research rather than arbitrage or edge tracking.

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

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

The description provides strong context for when to use the tool: 'Use for ...' plus concrete fan-out examples for different bet types. It also offers behavioral guidance like 'ALWAYS inspect these before trusting the analysis block' and 'Check this before sizing sports/esports/event-occurrence bets.' However, it does not explicitly name alternatives or state when NOT to use this tool versus the sibling tools, so it stops short of a 5.

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

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

Beyond the annotations, the description discloses what the tool returns (risk assessment, confidence score, signals) and warns that the keyless anonymous quota is shared and usually spent. The BYO API key guidance is actionable and non-obvious.

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 front-load the purpose, then explain outputs, then cover the key requirement. Every sentence adds value and there is no filler.

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

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

For a simple two-parameter read-only lookup with an output schema, the description covers the use case, result semantics, and credential requirement. Nothing essential is missing.

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

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

Input schema coverage is 100%, so both parameters are already documented in the schema with detailed descriptions. The description reinforces the _apiKey quota warning but adds no new parameter-level semantics beyond that repetition.

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

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

The description names a clear verb ('Check'), a specific resource ('a domain'), and the exact purpose (disposable/temporary email services). It also mentions the return values (risk assessment, confidence score, signals), which distinguishes it from domain-adjacent siblings like validate_email.

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 use case is explicit: domain-level disposable email detection. It does not explicitly name alternatives or state when not to use it, but the domain-versus-email framing gives clear context for selection.

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 marking it read-only and idempotent, the description adds substantial behavioral context: it details data sources (SEC EDGAR/XBRL, FAERS), fiscal year handling (AAPL Sep, NVDA Jan), sorting by primary metric, and that output includes paired data and citation URIs. No contradiction with annotations.

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

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

The description is somewhat long but well-organized: trigger phrases first, then behavior, then data sources, then output. Each sentence adds value, and the front-loading of example queries makes it immediately actionable. A slightly tighter structure could earn a 5, but it remains efficient.

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

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

With no output schema, the description covers both input and output well: it explains what metrics are pulled for each type, how they're sorted, that results are paired, and includes citation URIs. It also addresses edge cases like off-calendar fiscal years, making it highly complete for a tool with only two simple parameters.

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, but the description enriches meaning by explaining what 'company' vs 'drug' types return (e.g., 10-K revenue vs FAERS counts) and giving concrete value examples (tickers/CIKs for company, drug names for drug). This goes 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 clearly states the tool performs 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It includes concrete trigger phrases ('X vs Y', 'which is bigger') and distinguishes itself from siblings by explicitly noting it replaces sequential single-pack lookups.

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

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

Provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Describes the exact scenarios (comparison, ranking, head-to-head) and even differentiates between company and drug use cases, making it clear when this tool is the right choice.

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 readOnly/idempotent/destructive hints, and the description adds substantial context beyond that: account and paid-tier requirements, parallel facet decomposition, findings packet structure, explicit gaps[] instead of invented answers, resolvable citation_uri guarantee, contradictions[] scans, semantic excerpting, and expected latency of 15-60s up to ~90s. No contradiction with annotations.

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

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

The description is long but information-dense, front-loading the most actionable fact (account required). Every sentence adds a distinct operational detail — scope, exclusions, output, latency, citation behavior — with minimal filler. A few clauses could be tightened, but the density earns a high score.

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

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

Given the tool's complexity, lack of output schema, and need to choose among siblings, the description is complete: prerequisites, tier restrictions, exact output shape, gap behavior, citation resolution, hop behavior, and runtime expectations are all covered. The example questions further ground the intended use.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: depth values are explained behaviorally ('standard re-angles unanswered gaps', 'thorough chases leads'), and the question parameter is clarified as accepting broad/multi-part natural language that gets decomposed. This goes beyond the schema's simple field 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?

States a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1497 STRUCTURED data sources... in ONE call', and distinguishes itself from open-web search and the ask_pipeworx siblings. The mechanism (decomposes into facets, routes to 5,724 tools in parallel) and return format are clearly described.

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 names alternatives and selection criteria: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. Also states its own best-fit: 'Best for broad/multi-part questions over structured data'.

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 idempotentHint=true, so the safety profile is known. The description adds valuable behavioral detail beyond annotations: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and notes results are 'ready to call directly, no second schema lookup needed.' This clarifies the return format and eliminates the need for follow-up lookups, which is not visible in annotations.

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

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

The description is front-loaded with a one-line purpose, followed by a compact domain list, and ends with clear return-value and usage guidance. Each sentence earns its place; the domain list, though long, is directly useful for query composition and does not feel padded. It is appropriately sized for the tool's discovery role.

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 read-only, idempotent discovery mechanism with no output schema. The description compensates fully by specifying what is returned (names, descriptions, full schemas, curated examples) and that results are directly callable. Combined with annotations and a rich input schema, the description gives the agent everything it needs to invoke the tool effectively.

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

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

With 100% schema description coverage, the baseline is 3. The description adds extra semantic value by enumerating a wide range of domains (SEC filings, FDA drugs, FRED, Census, etc.) that help the agent formulate a rich query for the 'query' parameter. It also reinforces that the query is a natural language description of a data task, going beyond the schema's examples.

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

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

The description opens with a specific verb and resource: 'Find tools by describing the data or task.' It clearly distinguishes itself from siblings by positioning as a meta-tool for discovery, with explicit direction to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This leaves no ambiguity about its purpose.

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

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

The description explicitly states when to use it: 'Use when you need to browse, search, look up, or discover what tools exist.' It also gives guidance on when to prioritize it ('Call this FIRST') and lists the data domains it covers, making the decision to invoke it straightforward against the many sibling tools.

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

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

Annotations already confirm read-only/idempotent/non-destructive, but the description adds significant behavioral context beyond that: it fans out in one parallel call, returns specific data points (CIK, recent filings with URIs, latest 10-K fundamentals), discloses the USPTO patents API sunset with soft-fail behavior, explains the GDELT→GNews fallback, and requires zero-padded CIKs. This is exactly the kind of context that helps an agent predict side effects and edge cases.

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

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

The description is dense but well-structured: example triggers, core purpose, return fields, caveats, and input constraints. Every sentence carries useful information for tool selection and invocation. It is longer than the calibration's ideal two-sentence example, but the tool's complexity justifies the length, and the content is front-loaded with purpose and usage.

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

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

Given the tool has no output schema, the description must explain return values, and it does: list of fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) with details like URIs and sorting. It also covers failure modes (patents sunset), fallbacks (news), and input prerequisites (ticker/CIK, not names). This is complete for a read-only profile tool with strong annotations.

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

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

Schema description coverage is 100% — both 'type' and 'value' are fully described in the schema. The description adds minor emphasis with examples ('AAPL', '0000320193') and restates the name-not-supported rule, but does not introduce new parameter semantics 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 states a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call.' It enumerates the sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return fields, and explicitly differentiates from sibling single-pack lookups by positioning this 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?

Provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also states a clear exclusion: names are not supported, directing to resolve_entity if only a name is available. This gives the agent actionable decision rules.

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 destructiveHint=true and idempotentHint=true, covering the safety profile. The description adds context about what is destroyed (previously stored memory by key), which goes beyond structured fields, though it does not elaborate on edge cases like missing keys.

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

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

Three concise sentences each serve a purpose: purpose, usage scenarios, and sibling references. No filler or redundancy; front-loaded with the core action.

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

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

For a single-parameter deletion tool with strong annotations, the description covers purpose, usage, and related tools. With no output schema, no return-value explanation is needed, and the description is complete for its 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% and the key parameter is well-described in the schema. The description repeats the 'by key' concept but adds no additional semantic detail beyond what the schema already provides, so baseline 3 applies.

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

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

Clearly states the action (Delete) and resource (stored memory by key). Distinguishes from sibling tools remember and recall by naming the operation and pairing them, making its role unmistakable.

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

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

Explicitly provides when-to-use scenarios (stale context, completed task, sensitive data cleanup) and references sibling tools remember and recall for coordination. Meets the 'when/when-not/alternatives' bar by offering concrete usage guidance.

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

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

The description discloses behavioral details beyond the annotations: it fetches the page, extracts title/description/key links, and emits a text blob. This complements the readOnlyHint and idempotentHint annotations by explaining how the tool operates. No contradiction with annotations.

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

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

The description is concise, with two sentences plus a 'Useful for' list. It front-loads the primary purpose and every sentence contributes value, including the usage scenarios and output format. No wasted words.

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

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

Given the tool's moderate complexity (fetching a URL, processing, returning a text blob) and strong annotations, the description adequately covers what the tool does, its output, and likely use cases. It does not mention potential caveats like network errors, but these are not essential for tool selection and invocation.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters. The description adds no new semantic detail about parameters beyond what is in the schema, thus meeting the baseline of 3 without further enhancement.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It distinguishes itself from sibling tools by naming the exact output (llms.txt) and explaining the process of fetching, extracting, and emitting standard markdown.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), which clearly indicate when to use the tool. However, it does not mention alternatives or when NOT to use it, lacking explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the scope (caller's own subscriptions) and the default filtering to active ones, and it lists the exact fields returned, which is not in the annotations nor an output schema.

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

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

The description is two sentences long and front-loaded with the action and resource. Every phrase earns its place—scope, return fields, and use case all in one compact text.

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 low complexity with one optional param and no output schema, but the description lists return fields, making the response clear. Annotations cover safety and idempotency. The tool's purpose, usage, and behavior are fully captured for an agent to invoke it correctly.

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

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

The single parameter include_inactive is fully described in the schema (default false), so schema coverage is 100%. The description does not explicitly mention the parameter, but it refers to 'active subscriptions' which aligns with the default. No additional semantic information is needed, so baseline score of 3 is appropriate.

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

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

The description clearly states it lists the caller's active subscriptions and enumerates the return fields (id, type, params, created_at, last_fired_at, fire_count). This distinguishes it from sibling tools like subscribe and unsubscribe by focusing on the read-only listing action.

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 'to review what you're monitoring before adding more or to find an id to cancel,' which gives concrete when-to-use context. It implies alternatives by referencing the actions of adding more (subscribe) and cancelling (unsubscribe), though it doesn't name them directly. This is clear enough for an agent to select appropriately.

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

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

Annotations are all false, leaving the description to carry the full burden. It discloses key behaviors: filing without an account returns a claim_token for later follow-up, responses are read daily, rate limit of 5 per identifier per day, and that it does not count against tool-call quota. These go well beyond what annotations provide and help set agent 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 longer than average, but every sentence contributes: purpose, exclusions, usage categories, claim_token flow, daily digest, rate limit, and quota note. It is front-loaded with the core 'tell the team' purpose and structured logically, though it could be slightly tightened or broken into bullets without losing impact.

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

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

There is no output schema, so the description must explain response behavior. It fully covers the claim_token return and follow-up flow, clarifies who reads the feedback and how often, and states the rate limit. For a tool with four parameters, zero required, and nuanced routing rules, this description leaves no important gap.

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

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

While schema coverage is 100% (baseline 3), the description adds extra semantic value by explaining the claim_token lifecycle: 'Filing without an account returns a `claim_token`; pass it back later... to read whether it was fixed.' It also implicitly maps the type enum values to real-world scenarios, which the schema also describes but the description reinforces concisely.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling tools by explicitly stating it's only for issues with tools served by this Pipeworx connection and not for other MCP servers, making its scope unambiguous.

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

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

The description provides explicit when-to-use scenarios ('bug', 'feature/data_gap', 'praise') and an explicit when-not-to-use rule ('if the tool came from a different MCP server... file it with that server instead'). It also offers a fallback heuristic ('Pipeworx tool names are the ones this connection lists'), which is excellent guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavior: caching ('Cached 5min-1h'), privacy ('no PII'), and data provenance ('derived from CF analytics-engine'). This goes well beyond the annotations, though it doesn't cover failure modes or exact response structure.

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

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

Four sentences, each packed with purpose: definition, outputs, use cases, and behavioral caveats. It's efficient and front-loaded, though not as terse as a two-sentence ideal.

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

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

For a single-param read-only tool with no output schema, the description fully covers what it returns, why to use it, and important caveats (caching, privacy). It leaves little ambiguity about the tool's role in the workflow.

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

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

Schema coverage is 100% with a well-described window enum. The main description only mentions the window options without adding new semantics; the schema already explains the default and the hot-vs-steady-state tradeoff. Baseline 3 applies.

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

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

The description opens with a clear, specific statement ('What other AI agents are calling on Pipeworx right now') and explicitly lists the outputs ('top tools, top packs, and total call volume'). It distinguishes itself from sibling tools like discover_tools or recent_changes by focusing on aggregate trending behavior over a time window.

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 'Useful for:' list provides three explicit scenarios (discovering hot data sources, confirming canonical tools, aligning use case with agent demand), giving clear guidance on when to invoke this tool. It doesn't mention exclusions or 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?

The description discloses far more than annotations: it explains the partition filter ('drops will-person-X / will-manager-Y...'), the semantic anchor ('≥0.30 Jaccard similarity'), and the fill check ('realizable_edge_pp ≤ 0 means... do not trade'). These add context about output reliability and edge cases, complementing the read-only/idempotent hints without contradiction.

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

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

The description is long but well-structured, with clear sections for modes, filters, and response. Every sentence adds technical detail or usage guidance. It could be slightly tighter (e.g., condensing the partition_check explanation), but the density is justified 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?

Despite having no output schema, the description explicitly outlines the response structure: 'Response: opportunities[] (gap_pp, suggested_trade, reasoning...), and in event mode partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}.' It also covers behavioral nuances (fill check, similarity filter) that are essential for correct invocation and interpretation. Fully complete for a read-only analytical 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% and each parameter already has a rich description, but the tool description goes further by explaining the mechanics: event mode 'walks child markets, checks date-axis / threshold-axis ordering AND computes the partition_check', while topic mode 'searches related events... flattens markets, runs the comparator on the union.' This adds meaning beyond the schema's 'when to use' phrasing.

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+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from siblings by detailing the fill-check integration and referencing polymarket_fill_risk, making it unique among similar Polymarket tools.

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

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

Provides explicit usage scenarios: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', or 'topic for a themed cross-event scan.' It even recommends when to prefer one mode, and names an alternative tool ('For custom sizing use polymarket_fill_risk').

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, idempotentHint, etc.), the description discloses rich behavioral details: the five model families and their logic, the response structure (by_segment, fed_candidates, _diagnostics), caching at KV level, and per-opportunity fields like edge_pp_net and the 24h-move warning. It also explains why segments might be empty (top-N stale, failed gates, knobs), which is not inferable from annotations alone.

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

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

The description is long but well-structured, starting with the purpose, then detailing the model families, opportunity fields, knobs, and response structure. It is front-loaded with the main use case, but the density of technical specifics (e.g., FRED log-returns, GDELT ratios) may be more than needed for tool selection. Overall, it earns its length for a complex tool, though trimming would improve conciseness.

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

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

With no output schema, the description fully explains the return structure: by_segment with three named segments, fed_candidates/fed_note, and _diagnostics with funnel counters and filter_skips. It also covers edge fields, caching behavior, and why certain segments may be empty. The description is sufficiently complete for an agent to understand what the tool returns and how to 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?

While the input schema has 100% coverage for parameter descriptions, the tool description adds meaningful interaction semantics: it explains that min_partition_leg_kelly applies to per-leg Kelly within top_legs instead of min_kelly, and groups params as 'TRADEABLE-EDGE KNOBS' to clarify their role. This goes beyond the schema's individual descriptions, though it doesn't add syntax details for every parameter.

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

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

The description opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly differentiates from sibling tools like polymarket_arbitrage by focusing on Pipeworx data disagreement and daily discovery, and it details the three response segments to illustrate the tool's unique value.

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 the tool is 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets,' providing clear context for when to use it. It also explains knob usage (e.g., max_spread_pp, min_partition_leg_kelly) and the Fed note, but it does not explicitly name alternatives or provide when-not-to-use conditions relative to siblings.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description goes far beyond by detailing the response structure (tracked[], expired[], snapshot_dates[]), explaining snapshot gaps due to cache-miss behavior, and disclosing limitations (60-day TTL, decay computed from daily closes not intraday). No contradictions with annotations.

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

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

The description is dense but well-structured with labeled sections (ARGS, RESPONSE, LIMITS). Every sentence provides meaningful information—no filler. It is longer than typical, but for a complex telemetry tool with detailed output, the length is justified and readability is enhanced by clear segmentation.

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 there is no output schema, the description compensates by defining every response field and its semantics, including edge_pp_net time-series, trend values, decay calculations, and snapshot_dates. It also outlines important limitations (history depth, TTL, non-intraday decay). This is a complete and self-contained reference 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% with both params having descriptions. The description adds minimal extra nuance (e.g., 'window (snapshot family, default 1wk)') and slightly less precise on days (says max 30 vs schema clamp 2-30). Since the schema already documents parameters thoroughly, the description's contribution is marginal, 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?

Description clearly states 'Edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?' It differentiates from sibling polymarket_edges by focusing on historical snapshots and decay trends rather than current edges. The verb 'tracker' plus explicit resource ('daily polymarket_edges snapshots') makes 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?

Provides strong context on when to use: to evaluate edge persistence/decay and understand competitive lifespan. It also explains data generation (snapshots written on cache-miss), which informs users about gaps. However, it does not explicitly name alternative tools or state when not to use it, leaving some implicit differentiation.

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

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

Beyond the annotations (read-only, idempotent), the description discloses detailed behavioral traits: it walks the order-book ladder, returns verdicts (clean|degraded|cannot_fill), interprets size_usd differently per mode, and highlights the risk of partial basket fills transforming an arb into an unhedged directional position. This provides deep context that annotations alone do not convey.

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

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

The description is dense and information-rich, but quite lengthy. However, every section (purpose, requirements, mode-specific details, output fields, usage warning) earns its place given the tool's complexity. It could be slightly more concise, but the structure is logical and front-loaded with the core purpose.

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

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

For a tool with four parameters, two modes, and no output schema, the description is remarkably complete. It covers outputs (top_of_book, vwap_fill_price, capture_ratio, thin_legs, etc.), default behaviors, constraints, and risk implications in detail. Given the complexity, the description fully satisfies the need for operational guidance.

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

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

Schema coverage is 100%, but the description adds significant meaning: side defaults and mode-specific interpretation, size_usd as 'max spend' vs 'target proceeds' vs 'settlement notional', and the difference between market and event parameters. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's function as a 'realizable-vs-theoretical edge check against live CLOB order-book depth' – a specific verb and resource. It distinguishes two modes (single-market and basket) and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges. This makes the purpose unambiguous and well-differentiated.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains the risks of not using it (partial fills convert arb to unhedged directional position). It also clarifies which mode to use for which scenario, providing clear when-to-use guidance relative to alternatives.

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

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

The description goes far beyond the annotations by disclosing the heuristic matching process, the meaning and non-empty nature of compatibility codes, the absolute exclusion of unknown legs, the null semantics of temporal_alignment, fee-schedule grossness, and skipped-comparison counters. It also warns that returned pairs may still be mismatched and that pre-mapped does not mean tradeable. There is no contradiction with readOnlyHint or idempotentHint.

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 densely informative and front-loaded with the core purpose, but it is very long and somewhat repetitive, repeating the same matcher behavior and temporal-mismatch warnings in multiple places. Most content earns its place, but tighter editing would improve scannability for an agent.

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

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

The description is highly complete for a complex tool with no output schema. It covers the two invocation modes, response fields, safety semantics, compatibility codes, fee caveats, skipped leg counters, and common pitfalls. An agent has enough context to call the tool safely and interpret ambiguous results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning beyond the schema. It explains that topic auto-fetches the matching event, that explicit tickers override the topic-mapped side, that both modes run the same matcher, and it expands on examples for kalshi_event_ticker and polymarket_event_slug. This is useful semantic enrichment over the raw schema.

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

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

The description clearly identifies a specific resource and operation: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It also explains two distinct usage modes. However, it does not explicitly distinguish itself from closely related siblings like polymarket_arbitrage, so it misses the full sibling-differentiation bar.

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 detailed in-tool guidance: when to use topic shortcuts versus explicit tickers, what the tool does when bet shapes differ, and warnings that pre-mapped topics are often not tradeable. It does not, however, state when to prefer this tool over an alternative sibling, such as polymarket_arbitrage or polymarket_edges. The context is clear but the when-not-to-use guidance is limited to internal modes.

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 idempotentHint=true, so the safety profile is covered. The description adds valuable context beyond annotations: it discloses the dual behavior (retrieve single vs. list all), the scoping to identifier (anonymous IP, BYO key hash, or account ID), and the relationship with remember/forget. This enriches the agent's understanding, though return format on missing keys is not detailed.

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

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

The description is front-loaded with the verb 'Retrieve' and delivers all essential information in three dense sentences. No filler or redundant phrasing; every clause earns its place, including the scoping note and companion tool pairing.

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, read-only tool with strong annotations, the description is fully complete. It explains functionality, usage context, scoping, and related tools. Even without an output schema, the description's phrase 'Retrieve a value' and 'list all saved keys' sufficiently conveys the expected return behavior.

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

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

The input schema already covers the 'key' parameter at 100% with 'Memory key to retrieve (omit to list all keys).' The description adds further meaning by giving concrete examples of what keys might contain (user's target ticker, address, prior research notes) and by explaining that omitting the key yields a list, reinforcing the parameter's optionality and its role in the tool's dual behavior.

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 action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This clearly differentiates recall from its siblings remember and forget, and the examples (ticker, address, research notes) further clarify the intended resource.

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 recall: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also provides exclusions and alternatives by pairing with 'remember to save, forget to delete,' giving the agent direct guidance on when not to use recall.

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

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

The annotations declare readOnlyHint=true and destructiveHint=false, indicating a safe, non-mutating read operation. However, the description states that setting mark_read:true will flag returned events as read and cause the next call to show only newer ones, which is a state-changing side effect. This directly contradicts the readOnlyHint annotation, making it a serious transparency issue.

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 and front-loaded with the primary purpose. Each sentence contributes information: return payload, filter options, mark_read side effect, polling note, and alternative access. It is a bit longer than necessary but remains concise and readable. No filler or repetition beyond the title, hence a 4.

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 5 parameters and no output schema, the description thoroughly covers the return format (source, citation_uri, raw event payload), filtering, mark_read behavior, polling suitability, and an alternative REST endpoint for scripts. This is comprehensive and equips the agent with enough context to use the tool correctly. The contradiction with annotations is a flaw in annotation consistency, not in the completeness of the description itself.

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

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

The input schema covers all parameters (100% coverage), so the baseline is 3. The description adds meaningful context beyond the schema by explaining how parameters interplay: filtering by type (e.g., 'sec_8k'), since as an ISO timestamp, and the behavior of mark_read affecting future calls. It also notes default behavior (e.g., default false) implicitly. This added value warrants a 4.

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

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

The description clearly states the tool pulls fired events from the user's subscription feed and returns recent alerts. It uses a specific verb ('Pull') and resource ('fired events from your subscription feed'), distinguishing it from sibling tools like list_subscriptions and recent_changes by focusing on alerts the evaluator has written to the persisted feed.

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

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

The description gives clear context on when to use the tool: to retrieve fired alerts from the feed, with optional filtering by type and since. It also mentions polling is fine and provides an alternative REST endpoint for scripts. However, it does not explicitly exclude other tools or compare with alternatives like list_subscriptions or recent_changes, hence not 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 readOnlyHint annotation, the description discloses multi-source fan-out to SEC EDGAR, GDELT/GNews, and USPTO, including fallback logic and the USPTO soft-fail due to API sunset. It also details input format and return structure, providing rich 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 but well-structured: it opens with usage phrasings, states the core purpose, explains the fan-out sources and fallback, parameter formats, return shape, and the alternative tool. Every sentence contributes meaningful information.

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

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

Given the complexity of the tool and no output schema, the description covers purpose, sources, behavior, parameters, and return structure. It falls short only on detailing the exact shape of a change item, but this is a minor gap given the overall completeness.

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 carries the parameter descriptions. The description adds valuable examples for `since` (e.g., '7d', '30d', '3m', '1y') and `value` (ticker or zero-padded CIK), enriching the semantics 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 clearly identifies the tool as a change feed for a company over a recent time window, using example phrasings like 'What's new with X' and 'latest on Y'. It distinguishes itself from sibling entity_profile by noting it is time-windowed, whereas entity_profile provides static profiles.

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

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

It explicitly states when to use the tool with example queries and provides a direct alternative: 'Use entity_profile instead when you want the static profile...'. It also explains the fallback behavior from GDELT to GNews, giving the agent a clear decision framework.

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 (idempotent, non-destructive), the description adds important details: storage as a key-value pair scoped by identifier, and persistence differences between authenticated (persistent) and anonymous (24 hours) sessions. This provides meaningful behavioral context not present in 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 three sentences, front-loaded with the primary purpose in the first sentence. Each sentence contributes distinct, essential information (purpose, usage context, persistence/lifecycle) without 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?

Given the simple schema, annotations, and this tool's nature, the description covers purpose, when to use, scoping, persistence, and how it relates to sibling tools. It omits details about return value or overwrite behavior, but these are largely implied by the idempotent annotation and are unlikely to hinder correct use, so a small deduction is applied.

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

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

The input schema has 100% coverage with descriptions and examples for both key and value. The description adds only minor context about key-value scoping, which does not significantly surpass the schema's own parameter documentation, hence the baseline score of 3.

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 action ('Save data the agent will need to reuse later') with a clear resource and scope. It distinguishes from siblings by explicitly mentioning recall and forget for retrieval and deletion, and provides concrete examples of what to store.

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

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

The description explicitly says 'Use when you discover something worth carrying forward' and gives examples, which is clear positive guidance. It also names alternatives (recall, forget) for related operations, fulfilling the when/alternatives requirement.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds substantial behavioral context beyond those annotations: it cascades through multiple lookup endpoints, returns `figi_candidates` on ambiguous matches, reports unresolved identifiers explicitly under `unresolved`, and degrades gracefully when GLEIF/OpenFIGI are unavailable. 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 dense but front-loaded: it opens with concrete user queries and the 'Use FIRST' guidance before diving into type-specific details. The prose is long and somewhat sprawling with many parentheticals, but most clauses carry real decision-relevant content, so it earns its length for a tool with this 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?

With no output schema, the description carries the burden of explaining what the tool returns, and it does so thoroughly: it names the identifiers returned per type, the `unresolved` field, the `figi_candidates` ambiguity case, and the graceful-degradation behavior. An agent has enough information to decide 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?

Schema coverage is 100%, so the baseline is 3, and the schema already documents `type` and `value` thoroughly. The description adds semantic meaning beyond the schema by noting that ISINs are accepted for company resolution, that an ISIN resolves to the issuing legal entity via GLEIF, and that drug lookup accepts both brand and generic names. This meaningfully exceeds the schema but still leaves some parameter behavior articulated in the schema rather than the description.

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

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

The description clearly states the tool's job: resolving a user-spoken name into canonical/official identifiers like CIK, LEI, FIGI, and RxCUI that other tools require. It goes beyond the title by enumerating supported entity types and example queries, but it does not explicitly contrast itself with sibling tools such as entity_profile or compare_entities, stopping 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 gives an explicit selection rule: 'Use FIRST whenever you have a name but need an ID,' reinforced by example user phrasings. It establishes clear context for when this tool is appropriate, but it does not state exclusions or name alternative tools to choose instead, so the guidance is strong but not exhaustive.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral detail beyond those annotations: it explicitly says the tool 'probes each entity with ai_visibility_check', 'ranks by score', and returns 'score, confidence, signal density'. No contradiction with annotations.

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

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

Two sentences deliver action, method, use case, and output expectations with zero filler. The content is front-loaded with the primary purpose and includes a concrete example, making it highly scannable.

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 moderate complexity (4 params, no output schema), the description is thorough: it names the downstream tool, explains the ranking behavior, lists the return fields, and provides a realistic scenario. Combined with the fully documented schema and strong annotations, the description leaves few gaps for the agent to proceed 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%, and every parameter has a detailed schema description: models enumerates supported values, _apiKey explains the conditional requirement, context gives disambiguation purpose, and entities explains count and first-entry semantics. The tool description reinforces these at a high level but does not add new parameter-level information 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 opens with a specific action and resource: 'Compare AI visibility across multiple entities side-by-side'. It clearly distinguishes from the sibling ai_visibility_check by noting it probes multiple entities and returns a ranked comparison, not just a single check.

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

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

The description gives a concrete use case: 'competitive AI-marketing audits', and even provides an example query. It implies this tool is for multi-entity comparison and mentions ai_visibility_check as the underlying probe, but it stops short of explicitly stating when to prefer this over sibling compare_entities or when not to use it.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds critical behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. It also discloses the NPM-only v1 limitation, going well beyond the structured 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 information-dense without filler. It front-loads the core purpose, then methodically lists sources, return fields, usage guidance, scope limitations, and failure behavior. Every clause earns its place, and the use of em-dashes and parentheticals keeps it 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?

For a complex composite tool with no output schema, the description fully covers return values (summary block fields, per-advisory detail, links, alternatives), failure modes, latency expectations, and ecosystem restrictions. It leaves no significant ambiguity about what the tool does or what the agent should expect.

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

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

Schema coverage is 100% for both parameters (package and version), including descriptions for scoped packages and default-to-latest behavior. The description adds a bit of context around version resolution but primarily relies on 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 opens with a concrete, specific verb+resource: a composite check for 'should I add this npm package to my project' that fans out across deps.dev and bundlephobia. It clearly defines the tool's unique function and scope, distinguishing it from any generic 'scan' operation.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' guiding users to alternative approaches for non-npm ecosystems.

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

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

The description goes well beyond the annotations by detailing behavior: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char overlapping windows, and caps input at 200K chars with truncation flags. This discloses algorithmic details, output format, and edge-case behavior, while annotations already cover safety (readOnly, idempotent, non-destructive). No contradiction.

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

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

The description is concise yet information-dense. Each sentence earns its place: core function, examples, use case, pairing, technical parameters, and truncation behavior. It is front-loaded with the primary purpose and does not waste words.

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

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

Given no output schema, the description compensates by explicitly stating return values: 'get back the top-N passages with character offsets and similarity scores.' It also covers usage, alternatives, and edge cases (truncation), making it fully self-contained 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 description coverage is 100%, so the baseline is 3. The description adds minimal new parameter-specific meaning—it reiterates that 'text' is the document, 'query' is natural language, and 'limit' exists, but the schema already provides these. It does not introduce additional syntax or format details beyond the schema.

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

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

The description clearly states the tool's function: 'Semantic search INSIDE a fetched record.' It specifies the verb (search), resource (a fetched record), and scope (inside, not across records). It also distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded, establishing a specific niche.

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 conditions when to use: 'Use when the record is too big to cram into the prompt.' It also names an alternative and how to combine: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This provides clear when-to-use and a comparison.

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 important behavioral traits beyond the annotations: authentication requirements, the fact that subscriptions cannot persist for anonymous/BYO accounts, return of a subscription id, and constraints like SMS phone verification and a 10/day cap. It does not contradict the annotations (readOnlyHint false, idempotentHint true).

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 relatively long but front-loaded with the core action and return value, then organized by supported types and delivery channels. Each sentence adds useful information, but the dense prose could be more readable with better formatting. It remains appropriately sized for the complexity.

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

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

Given the tool's complexity and the rich schema, the description covers the critical aspects: purpose, required auth, main subscription types, delivery channels, and constraints. It omits two enum types (patent_grant, clinical_trial) and webhook delivery in the description, but the schema fully covers those, so the overall picture is complete enough for correct invocation.

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

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

The schema already provides 100% parameter coverage with detailed descriptions for each parameter, including type-specific filters and delivery channel properties. The tool description adds some examples like items:["5.02"] and topic:"fed" but these largely overlap with the schema. It does not substantially enhance parameter understanding beyond what the schema offers.

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

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

The description clearly identifies the tool as creating a proactive monitoring subscription to a live-data event stream, with a specific verb ('Create') and resource. It also differentiates from siblings like list_subscriptions and unsubscribe by focusing on the creation action, and notes the return value (subscription id).

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: it requires a Pipeworx OAuth account, is not available for anonymous/BYO users, and gives delivery channel options including the always-on feed and optional email/SMS. It does not explicitly exclude alternatives or state when not to use it, but the context makes it clear enough for an agent to select appropriately among siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds useful behavioral context beyond annotations, such as returning category-bucketed examples with tool+argument shapes and drawing from the live catalog of thousands of tools. There is no contradiction with annotations.

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

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

The description is verbose at around 80 words and includes a redundant list of categories already present in the schema. It does front-load the purpose effectively with the quoted user questions and maintains a logical structure, but every sentence does not fully earn its place due to 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?

Despite lacking an output schema, the description thoroughly explains what the tool returns (category-bucketed example questions with tool and argument shapes), how to invoke it (no arguments vs. topic), and when to use it (first step for onboarding). It is complete for its purpose.

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

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

The input schema already provides 100% coverage with a description of the optional 'topic' parameter, including allowed values and the behavior when omitted. The description restates these with examples ('finance', 'pharma', 'betting') but does not add new semantic information beyond what the schema provides.

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

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

The description clearly states the tool's function: it is the onboarding entry point for a newly connected agent, returning category-bucketed example questions with the exact tool and argument shape that answers each. It distinguishes itself from siblings like discover_tools by explicitly instructing to 'Use this FIRST' when learning what Pipeworx can do.

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

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

The description provides clear context for when to use the tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the optional topic parameter and the behavior when omitting it (full spread). However, it does not name alternative tools or give explicit 'when not to use' guidance, so it lacks full alternatives/exclusions.

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

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

The description goes beyond the annotations by disclosing ownership enforcement and the deactivation behavior ('The row is deactivated (not deleted) so its historical events stay available via recent_alerts.'). This adds valuable context not present in the annotations, and it does not contradict 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 three sentences, each earning its place: it states the action, the ownership constraint, and the deactivation side-effect. There is no unnecessary filler, and it is well-structured and front-loaded.

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

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

For a simple mutation tool with one parameter and no output schema, the description covers essential aspects: action, ownership, and data persistence behavior. It does not describe return values or error cases, but given the simplicity, this is a minor gap.

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

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

The schema already provides full coverage for the 'id' parameter, describing it as a UUID returned by subscribe. The description merely says 'by id' and adds no additional meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the action with a specific verb and resource: 'Cancel a subscription by id.' It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on the cancellation action and explicitly noting the deactivation behavior.

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

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

The description provides clear context for when to use the tool: to cancel a subscription. It also adds ownership constraints ('you can only cancel your own subscriptions'), which is a useful usage guideline, though it does not explicitly name alternatives or exclusion scenarios.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description goes beyond by explaining verdict semantics (confirmed, refuted, etc.), warning that could_not_verify means the check did not happen and must not be treated as evidence, and that unsupported means no source was found. This is critical behavioral context that annotations do not 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 dense but every sentence earns its place: trigger phrases, usage guidance, routing logic, return values, error semantics, and value proposition. It is well-structured, starting with the most critical cue phrases and ending with the efficiency benefit, with no fluff or repetition.

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

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

With no output schema, the description fully explains what the tool returns: a verdict, the actual value with citation, and reasoning. It covers edge cases (could_not_verify with verification_error, unsupported), both processing paths, and parameter overrides. This is a complete description for an agent to confidently 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?

Although schema coverage is 100%, the description adds substantial meaning to tolerance_pct by explaining that it overrides wording-implied tolerance and suggesting 1–2% for hallucination detection. It also provides concrete claim examples for the claim parameter, going well 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 clearly identifies a specific verb and resource: it verifies natural-language factual claims against authoritative sources. It lists concrete trigger phrases ('fact check', 'verify the claim that…', 'did X really…') and distinguishes two paths (structured SEC EDGAR for company-financial claims, grounded pipeline for all other claims), which separates it from sibling tools like resolve_entity or ask_pipeworx.

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

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

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives routing guidance (company-financial vs. other claims) and explains that it replaces 4–6 sequential calls, implying it is the single call for claim verification. It does not name alternatives directly, but the usage context is unambiguous.

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

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

Annotations already declare readOnly, openWorld, and idempotent behavior, but the description adds meaningful runtime context beyond those: this relies on Disify, DNS lookups, and disposable/alias checks, and the result is a live signal rather than a static local verdict. It also discloses the quota-sharing behavior of the anonymous tier. 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?

Three short sentences deliver the core behavior, the output, and the key operational caveat. The most important information is front-loaded, and there is no filler.

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

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

With a complete input schema, an output schema, and strong annotations, the description only needs to fill behavioral and practical gaps. It does so: what is validated, what is returned, and how to handle API key quota. Nothing essential is missing for an agent to call this 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 baseline is 3. The description's mention of _apiKey and the shared quota essentially replicates what the schema already explains; it does not add new parameter-level semantics beyond that.

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

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

The description names a specific verb ('Verify') and resource ('an email address'), then defines exactly what validation covers: formatting, DNS records, disposable status, and aliasing. It also states the return payload (status, 0-100 confidence score, signals), which clearly distinguishes it from broader tools like check_domain.

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

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

The description gives clear context for when this tool is appropriate by listing the checks it performs. It also gives important operational guidance: pass your own Disify key because the anonymous quota is shared and usually spent. It does not explicitly name alternatives or when-not-to-use conditions, so it stops short of a 5.

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