emojihub

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

Annotations already declare readOnly, openWorld, and idempotent hints. The description adds value by disclosing the default model (Workers AI Llama-3.3-70b) and cost implications ('BYO key — you pay Anthropic directly'), plus the return structure per model. This goes beyond annotations in terms of operational 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 three sentences, all packed with useful information. It front-loads the core purpose, then explains defaults and return format, then lists use cases. There is 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?

Despite no output schema, the description explicitly states the per-model response fields ('{score, confidence, signals, raw_response} + a combined view'). It covers default behavior, optional key usage, use cases, and cost implications. For a tool of this complexity, the description is complete and self-sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning by explaining the default model selection, the conditional need for _apiKey (only when 'anthropic' is in models), and the purpose of context for disambiguation. This enriches the parameter semantics beyond the schema.

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

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

The description uses a specific verb ('Probe') and clearly identifies the resource (one or more LLMs) and the concrete outcome (visibility score 0-100 per model). It distinguishes itself from siblings by focusing on AI visibility scoring across multiple models, including the default and optional model paths.

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

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

The description gives explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly mention alternatives or exclusions relative to sibling tools, but the use cases provide clear context for when this tool is appropriate.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses internal routing behavior, argument filling, and the structured output format with pipeworx:// citation URIs. It also adds operational context ('works on every tier, one fast call'). It does not mention failure modes or rate limits, so not a 5, but it is far beyond the annotation baseline.

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

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

The description is long but front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and each sentence contributes either domain coverage, usage triggers, examples, or sibling differentiation. The examples partially repeat the domain list, but the overall density is high 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?

Even with no output schema, the description states that the return is a structured answer with stable citation URIs, which is enough for an agent to know what to expect. It also covers when to use the tool, when to escalate, and what input formats are accepted. Missing details like error handling or rate limits are minor given the tool's simplicity.

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

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

Schema coverage is 100%, with the 'question' parameter fully documented and all aliases listed. The description adds meaningful examples ('current US unemployment rate', 'Apple's latest 10-K') that clarify what kinds of natural-language inputs are acceptable, going slightly beyond the schema's bare alias definitions.

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 ('routes', 'returns', 'fills arguments') and resource ('one of 5,708 tools across 1494 verified sources'), and explicitly positions itself as the default entry point over web search. It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by naming their different roles.

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

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

It provides explicit trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and says 'START HERE for most questions'. It also gives concrete escalation rules: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions, while noting breaking news is already covered here.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that routing improvements may be live only when a candidate is under test, that no candidate is currently active, and that the last candidate was retired on a specific date. It also explains that the beta currently matches ask_pipeworx exactly, which prevents surprise about identical behavior. No annotation contradiction is present.

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

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

The description is front-loaded with the core identity ('Beta version of ask_pipeworx') and immediately clarifies equivalence and scope. Every sentence earns its place: current candidate status, usage instruction, comparison purpose, and fallback reassurance. It is dense but not bloated, and 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?

For a single-required-parameter router tool with no output schema, the description is unusually complete: it explains the beta state, current equivalence to the stable router, when to prefer it, and that it is a fully functional router. An agent has enough information to invoke it correctly without additional context.

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%, with all six aliases documented in the schema itself. The description adds only that the tool takes 'same arguments' as ask_pipeworx, which is helpful but not essential given the complete schema. This meets the baseline for schema-covered 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 identifies ask_pipeworx_beta as a beta version of ask_pipeworx, a universal router with the same 5,708 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by stating this version carries candidate routing improvements when under test. The purpose is specific and actionable, not a tautology.

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 you want the newest routing, and clarifies that results are compared against the stable router to decide what merges. It also prevents misuse by stating it 'falls back to nothing' and is a full working router, not a degraded stub. This gives clear guidance for selecting this tool over its stable sibling.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses the refusal mechanism with specific reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), the restriction to only tool content, and the evidence-citing behavior. This is rich behavioral context that an agent needs to trust the output and handle failures.

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 with the core value proposition, then logically flows into process, return format, usage guidance, and trade-off. It earns its length, though a minor trim of redundant phrases like 'fills arguments' could tighten it further.

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

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

Despite no output schema, the description fully specifies the success and failure return shapes, including the refusal_reason enum. Combined with annotations and sibling context, the agent has everything needed to decide, invoke, and interpret results correctly.

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

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

The schema covers 100% of parameters, with all six effectively being aliases for question and documented in the schema itself. The description adds no new parameter-level semantics beyond what is in the schema, so the baseline of 3 is appropriate.

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

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

The description opens with a precise resource and behavior: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly states the tool extracts answers using only tool results, and differentiates itself from the sibling ask_pipeworx by being the grounded, high-stakes variant. The verb 'EXTRACTS' plus the explicit return/refusal contract leaves no ambiguity about what it does.

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

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

The description explicitly says when to use the tool ('Use whenever an answer will be quoted, cited, or acted on...') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'). It also notes the performance trade-off ('Costs one extra LLM call'), giving the agent actionable routing rules relative to ask_pipeworx.

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 hints. The description goes far beyond this by detailing the resolver contract (market_match_confidence, alternatives, suggestions), safety short-circuits (status:'low_confidence_match', market_closed_or_inactive), wide-spread tradeability warnings, and resolution-rule risk with cancellation_rule parsing. It also discloses GDELT fallback behavior with _fallback_attempted and retry_after_sec fields.

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

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

The description is long but front-loaded with purpose and usage, then systematically covers resolver contract, news fields, safety, and resolution rules using CAPS headers. While dense, each section adds actionable detail and there is no unnecessary redundancy. It earns a 4 for being appropriately sized to 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?

With no output schema, the description fully specifies response shapes (result.market, result.analysis, result.evidence, parent_event, news fields), status codes, and error conditions. It covers real-world edge cases like low-confidence matches, closed markets, wide spreads, and cancellation rules, leaving no ambiguity about return contracts.

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 input examples for market and explains fan-out behavior, but it does not materially extend the parameter semantics beyond what the schema already provides—especially for include_raw, where the schema already details payload sizes and use cases.

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 statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from siblings like polymarket_edges and polymarket_arbitrage by focusing on evidence gathering and market-vs-model comparison.

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

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

Explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear context for when to invoke, though it does not name specific alternative tools or exclusion criteria. Hence 4 rather than 5.

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

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

Annotations already indicate read-only, idempotent, non-destructive, and open-world behavior. The description adds rich context: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs in output. No contradictions.

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

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

The description is dense but well-structured, starting with trigger phrases, then usage preference, then type-specific details. Every sentence earns its place—no fluff. Length 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?

With no output schema, the description explains return values ('paired data + pipeworx:// citation URIs per entity') and sorting behavior. It also provides scale context ('Replaces 8–15 sequential lookups'), making it complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond schema by explaining what type='company' vs type='drug' pull (revenue, net income, adverse-event counts, etc.) and providing examples for values. It clarifies implicit behavior like fiscal-year handling.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs in one parallel call, with trigger phrases like 'X vs Y' and 'rank these companies'. It distinguishes from siblings by noting it 'ALWAYS PREFER over sequential single-pack lookups' and 'Replaces 8–15 sequential 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?

It explicitly says when to use this tool ('when comparing entities', 'ALWAYS PREFER over sequential single-pack lookups') and describes behavior for each type. However, it does not name specific sibling tools (e.g., entity_profile) as alternatives, making the guidance strong but slightly less explicit than a direct alternative reference.

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

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

Annotations already flag readOnly, idempotent, openWorld, and non-destructive, so the description earns credit for adding auth requirements, paid tier for 'thorough,' parallel facet decomposition, output shape (findings packet, gaps[], contradictions[], hop, citation_uri), the no-invention guarantee, and latency. It even notes citation_uri is present only when the source emits a resolvable URI.

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 definition is exhaustive and each sentence carries a distinct behavioral detail, but it is a long wall of text and opens with account requirements before stating its purpose. It could front-load the core function and trim repeated depth semantics.

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

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

With no output schema, the description compensates by describing the returned findings packet, citations, gaps, contradictions, and excerpts, plus latency and auth. 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 baseline is 3. The description does add useful context—good question examples and the behavior difference between quick/standard/thorough—but much of the depth explanation repeats the schema's own depth parameter 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?

Names the operation explicitly: 'Grounded multi-source research across Pipeworx's 1494 STRUCTURED data sources...' and contrasts it with ask_pipeworx. The verb+resource is distinct among siblings, and the 'NOT open-web search' qualifier prevents confusion with search-like 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?

Explicitly states 'Best for broad/multi-part questions over structured data' and then gives when-not-to-use guidance: single lookups, breaking/current-news, and unsigned-in users should use ask_pipeworx. This is strong routing guidance with named alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral detail beyond annotations: it returns top-N tools with names, descriptions, full input schemas and curated examples, and each result is ready to call directly without a second schema lookup. This is useful context about return behavior and does not contradict annotations.

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

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

The description is three sentences, each earning its place: what the tool does, when to use it, and what it returns. The domain list is long but directly helps an agent formulate a query. It is front-loaded with the most important information and contains 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?

There is no output schema, but the description compensates by explicitly stating the result format (names, descriptions, full input schemas, curated examples) and that results are directly callable. It covers purpose, usage, and output behavior, making it complete for a tool-discovery tool despite the absence of a structured output schema.

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

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

Input schema coverage is 100%: every parameter has a description, including the main 'query' parameter and its aliases (q, task, search, description) plus limit constraints. The description does not add parameter-specific detail beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb+resource pair ('Find tools by describing the data or task') and immediately frames the tool as the way to browse/discover what tools exist. It distinguishes itself from direct-answer sibling tools by explicitly saying 'Call this FIRST... to see the option set (not just one answer)', which sets it apart as a discovery/orchestration tool rather than a domain-specific lookup.

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' plus a prioritized rule 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)'. It also implies a when-not ('not just one answer') but does not name specific sibling alternatives, so it falls just short of a perfect score.

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

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

Annotations already declare readOnly/idempotent, so the bar is lower, but the description adds non-obvious behaviors: it fans out across five sources, lists exact return fields, discloses a known failure mode (USPTO PatentsView API sunset May 2025 with soft-fail) and describes a fallback chain (GDELT→GNews). These are valuable operational insights not present in annotations.

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

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

The description is long but information-dense and well-structured: it front-loads purpose with examples, then covers sources, returns, constraints, and alternatives in a logical order. Minor redundancy exists (e.g., repeating the 'company' theme), but each sentence earns its place, making it slightly above average but not perfectly concise.

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

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

For a complex tool with no output schema, the description is remarkably complete: it covers input semantics, output fields, source fallbacks, a known failure mode, and when to prefer this tool over alternatives. This is sufficient for an agent to select and invoke the tool correctly without further clarification.

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

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

The input schema already provides 100% parameter descriptions, including the enum for type and a detailed explanation of value (ticker or zero-padded CIK, names not supported). The description reiterates this with examples and adds the resolve_entity pointer, but does not meaningfully extend beyond the schema's own parameter explanations.

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

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

The description opens with concrete example queries ('Tell me about X', 'research Acme') and clearly states the tool produces a 'full cross-source profile of a US public company in ONE parallel call'. This distinguishes it from sibling tools like resolve_entity (name resolution) or compare_entities (comparison), and precisely specifies the action and 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 gives explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. It also states a clear exclusion (names not supported) and directs users to resolve_entity first, naming a concrete alternative.

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

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

Annotations already disclose destructiveHint=true and idempotentHint=true. The description adds the 'clear sensitive data' use case but does not explain behavior for missing keys, return values, or whether deletion is permanent beyond what annotations imply.

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

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

Three short sentences, front-loaded with the core action. The first sentence states what it does, the second gives use cases, and the third provides sibling context. 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?

This is a simple one-parameter destructive tool. With annotations covering safety and schema covering parameters, the description adds appropriate when-to-use context and sibling relationships. Fully adequate for the tool's complexity.

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

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

Schema coverage is 100% for the single required 'key' parameter, and its description ('Memory key to delete') fully explains its meaning. The tool description only repeats 'by key' and does not add meaningful extra semantics.

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

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

The description starts with a specific verb+resource: 'Delete a previously stored memory by key.' This clearly distinguishes the tool from siblings like remember and recall, which store and retrieve memories respectively.

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 ('context is stale, the task is done, or you want to clear sensitive data') and mentions pairing with remember and recall. It lacks an explicit when-not-to-use statement, but the guidance is otherwise clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds valuable process detail: it fetches the page, extracts content, and emits a standard llms.txt markdown blob. It also clarifies the output is a single text blob ready for placement, which is useful beyond the annotations.

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

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

The description is three sentences with a clear front-loaded purpose, a brief process breakdown, and a 'Useful for' list. No redundant phrasing; every sentence contributes to understanding what the tool does and when to use it.

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 two parameters, no output schema, and annotations covering read-only/idempotent behavior, the description provides sufficient context: input (any URL), process (fetch/extract), output (standard llms.txt markdown), and use cases. It is complete for an agent to select and 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?

Schema coverage is 100% (both 'url' and 'max_links' are described in the input schema). The description does not add extra meaning about the parameters beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Generate') and names the exact deliverable ('production-ready llms.txt file for any URL'). It clearly distinguishes this tool from siblings by focusing on the llms.txt generation workflow, including fetching the page, extracting title/description/key links, 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 'Useful for:' scenarios, such as getting a client's site indexed, drafting llms.txt for your own project, and auditing competitor AI visibility. However, it does not explicitly state when not to use it or name alternative tools, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the return behavior: 'Returns matching emojis with names and groups,' which is useful context beyond the annotations. It does not contradict any annotations, and the additional information is relevant and non-redundant.

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

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

The description is a single, concise sentence that front-loads the action and provides examples inline. There is no fluff or repetition; every word contributes to the tool's purpose and usage. It is perfectly sized for the tool's simplicity.

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 nature of the tool (one parameter, output schema present, detailed annotations), the description is sufficiently complete. It states the return format and provides example inputs. It does not explain pagination or sorting, but such details are not critical for a simple search-by-category operation. The combination of annotations, schema, and description covers the essential context.

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 for the 'category' parameter, including a descriptive text and examples. The description adds a few more example categories but does not fundamentally expand parameter understanding beyond what the schema already provides. With high schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: searching emojis by category. It uses a specific verb ('Search') and resource ('emojis'), and provides concrete examples of valid categories, which disambiguates it from sibling tools like get_by_group or random_emoji. The scope is well-defined.

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

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

The description implies usage for retrieving emojis filtered by a category, but it does not explicitly state when to use this tool versus alternatives like get_by_group or random_emoji. There are no exclusion criteria or alternative recommendations, leaving the decision to the agent's inference.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, lowering the burden. The description adds value by specifying the return content (names and categories) and providing concrete group examples, which is useful context beyond the annotations.

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

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

The description is a single, well-structured sentence that front-loads the main action ('Search emojis by group') and includes useful examples. Every word contributes, with no fluff or redundancy.

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

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

For a simple one-parameter tool with an output schema and strong annotations, the description is complete. It states the purpose, gives valid parameter examples, and mentions the return fields. No critical information is missing for effective 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 description coverage is 100%, and the schema already provides the group parameter description with examples. The description repeats the same examples, adding no significant semantic meaning beyond what the schema offers, so the baseline of 3 applies.

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

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

The description clearly states the tool searches emojis by group and provides specific group slug examples, making the purpose distinct. However, it does not explicitly differentiate from the sibling tool get_by_category, so it falls short of a 5.

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

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

The description implies usage through group examples and the stated search action, but it offers no direct guidance on when to use this tool versus alternatives like get_by_category. There is no explicit when-to-use or when-not-to-use context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context beyond the schema by specifying the return fields and the scoping to 'active' subscriptions by default, which clarifies the tool's behavior without contradicting the annotations.

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

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

The description is two sentences, front-loaded with the primary action, followed by return fields and usage guidance. Every sentence earns its place with no redundancy or 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 list tool with one optional parameter, rich annotations, and no output schema, the description is complete. It covers the tool's scope, return format, and use cases. The parameter is fully documented in the schema, so the description does not need to elaborate further.

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% for the single parameter include_inactive, which has its own description in the schema. The tool description does not add additional parameter-specific semantics beyond the schema, but it implicitly clarifies the default behavior with 'active subscriptions'. The baseline of 3 is appropriate given high schema coverage.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions. It also lists the exact fields returned, making the purpose unmistakable.

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

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

The description provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke this tool relative to subscribing (before adding) and unsubscribing (to get the id), effectively covering when and why 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?

All annotations are false, but the description carries the full burden and does so thoroughly. It discloses that filing without an account returns a claim_token, that the token can be used later to check status, that digests are read daily, that feedback is rate-limited to 5 per identifier per day, and that it does not count against tool-call quota. No annotation contradiction.

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

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

The description is a single substantial paragraph, but every sentence earns its place: purpose, usage criteria, exclusions, claim-token flow, rate limits, and quota impact. It is front-loaded with the primary purpose and then layers in necessary operational details. Slightly long, but for a tool with this many nuances, it is appropriately sized and well-structured.

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

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

Given that there is no output schema, the description fully compensates by explaining the return behavior (claim_token, later status check). It also covers edge cases like anonymous use, wrong-server feedback, and rate limiting. The tool is fairly complex with nested objects and optional params, and this description leaves no critical gap in understanding.

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

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

Schema coverage is 100% and the schema already describes each parameter clearly. The description adds significant meaning beyond the schema, especially for claim_token (pass with no other arguments to read a previous report's status) and for message content (be specific, don't paste end-user prompts). These additions justify a score above 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 specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from sibling tools by scoping it to Pipeworx tools, and elaborates on the four feedback types (bug, feature, data_gap, praise), making the purpose unmistakable.

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

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

The description provides explicit when-to-use guidance: for wrong/stale data, missing features, data gaps, or praise. It also gives a clear exclusion: if the tool came from a different MCP server, file elsewhere. It even explains how to use claim_token later, plus rate limits, leaving no ambiguity about when and how to invoke this tool.

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

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

Annotations already declare read-only/idempotent/non-destructive. The description adds meaningful details: self-aggregating signal, CF analytics-engine source, no PII, output shape, and caching window (5min-1h). This goes well beyond the annotations.

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

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

Each sentence earns its place: what it returns, when to use it, and behavioral details. The numbered use cases improve scannability without unnecessary fluff.

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

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

Despite no output schema, the description compensates by naming the return contents (top tools, packs, call volume). It covers data source, caching, privacy, and usage intent, making the tool fully specified.

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

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

Schema has 100% coverage for the window parameter, including enum values and semantic descriptions. The tool description merely restates the window options without adding new meaning, so it meets the baseline but adds little.

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 tool returns top tools, packs, and call volume from Pipeworx. The verb 'Returns' plus resource and scope makes it distinct from sibling discovery tools by focusing on aggregate trending data.

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

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

Provides three explicit use cases (discovering hot data sources, confirming canonical tool choice, aligning with agent needs). Doesn't explicitly mention alternatives, but the use cases give strong contextual 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?

While annotations mark the tool as read-only and idempotent, the description discloses critical behavioral details beyond that: the 3pp threshold for partition signals, placeholder filtering logic, and the fill-check pricing semantics (realizable_edge_pp ≤ 0 means do not trade). This adds substantial value beyond 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 long and dense, but it's front-loaded with the main purpose and uses clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). There is some repetition (partition_check mentioned twice), but every section adds operational value.

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

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

Despite lacking an output schema, the description spells out the response structure (opportunities[], partition_check, fill check), edge cases (thin_legs, skipped_low_similarity), and points to polymarket_fill_risk for sizing. For a complex multi-mode tool, this is remarkably 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?

The schema descriptions for event and topic are already detailed, but the description enriches them with concrete examples (event slugs, seed questions), mode-specific behaviors, and the semantic-anchor rule (Jaccard ≥0.30). This goes well beyond a standard schema definition.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool's purpose from siblings by detailing event and topic modes, and mentions related tools like polymarket_fill_risk.

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

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

Provides explicit usage guidance: call with no args for trending scan, pass event for specific markets, pass topic for cross-event scans. It even recommends which mode to use and directs to polymarket_fill_risk for custom sizing, offering clear alternatives.

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

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

Despite having readOnlyHint and idempotentHint annotations, the description adds substantial detail: the three model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), edge calculation with net slippage, Kelly caps at 0.25, 24h-move warning, placeholder-slug filters, diagnostics for empty segments, and caching behavior. This goes well beyond the annotations.

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

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

The description is an extremely dense, single-paragraph block with highly technical details (model formulas, alpha values, gate thresholds) that may be excessive for an agent deciding to invoke the tool. While front-loaded with purpose, it is not concise; many sentences are far beyond what is needed for selection and invocation.

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 thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics), field meanings (edge_pp_net, kelly_fraction, market.liquidity, spread_pp), and edge-case behaviors like why a segment might be empty. It fully covers the tool's complexity given 9 parameters and no schema.

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

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

Schema coverage is 100% (all 9 params have descriptions), so baseline is 3. The description adds value by explaining the purpose of tradeable-edge knobs (min_liquidity, max_spread_pp) and clarifying that min_partition_leg_kelly applies per-leg rather than parent-level, and that min_kelly does not filter partition arbs. This extra semantic context justifies a 4.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, explicitly positioning it for 'what should I bet on today'. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on Pipeworx data-driven edges.

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

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

The description provides clear context: it is for agents discovering opportunities without paging through hundreds of markets, and it explains the tradeable-edge knobs to filter results. However, it does not explicitly name alternatives or when-not-to-use scenarios, 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 readOnly/idempotent annotations, the description richly details behavior: the tracked/expired/snapshot_dates response structure, signed edge_pp_net meaning, 60-day TTL bound, cache-miss snapshot writing, and daily-close decay calculation. 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 organized into purpose, Args, RESPONSE, and LIMITS sections, with the core purpose front-loaded in the first sentence. Every sentence carries essential information; there is no filler or redundancy despite the length, making it efficiently structured.

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

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

With no output schema, the description fully documents return shape (tracked, expired, snapshot_dates) and limitations (TTL, snapshot gaps, daily-close basis). For a 2-param read-only telemetry tool, this is comprehensively complete and leaves no major ambiguity.

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

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

Schema coverage is 100% (both params described), so baseline is 3. The description adds value by stating defaults/clamps (days default 14, max 30), explaining window as 'snapshot family' (24hr/1wk/1mo), and grounding both in the response semantics. This exceeds schema basics but isn't dramatic.

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 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' – a specific verb+resource+scope. It clearly answers 'how long has this edge existed and is it shrinking?' and distinguishes itself from sibling polymarket_edges by focusing on temporal persistence rather than current edge values.

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

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

The description clearly implies when to use it: for assessing edge endurance and decay, contrasting fresh vs. old wide edges. It gives context but does not explicitly name alternatives or say 'use this instead of X', so it lacks explicit exclusion guidance. This is clear context without alternatives, earning a 4.

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

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

Beyond annotations (readOnlyHint=true, idempotentHint=true), the description discloses detailed behavior: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), interprets size_usd differently for buys vs sells and basket mode, and warns about forced_directional_risk. It also explains the 'no user/workspace filtering' equivalent by noting the requirement for market/event scope. 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 long but every major section earns its place: mode requirements, parameter explanation, output list, and usage context. It uses clear uppercase labels (SINGLE-MARKET, BASKET, REQUIRES, USE THIS) for scannability. It could be slightly tighter in listing all return fields, but the detail is functional rather than wasteful.

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

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

With no output schema, the description fully carries the burden of explaining return values — and it does, enumerating top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and verdict for single-market, plus theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], and forced_directional_risk for basket. It covers prerequisites, parameter semantics, and failure modes, making it complete for a complex two-mode 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%, but the description adds crucial semantic detail not in the JSON schema. It explains that size_usd means different things in single-market mode (max spend on buys, target proceeds on sells) vs basket mode (settlement notional S = shares per leg). It also clarifies the side parameter's default behavior and the 'auto' mode for basket. This significantly enhances the bare parameter list.

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 precise verb-resource pair: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by clearly framing this as a pre-trade risk validation. The two modes (single-market and basket) are explicitly defined, leaving no ambiguity about what the tool does.

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

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

The description gives explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (partial fills convert an arb into unhedged directional risk), giving strong contextual rationale. This directly names sibling tools and sets a threshold, making the decision process clear.

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

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

Annotations already indicate a safe, read-only operation, but the description goes well beyond them by disclosing how pairs are matched, why compatibility warnings can coexist with matched pairs, which legs are never paired, and what each safety code means. This is exemplary behavioral transparency.

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

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

The description is long but densely informative, clearly organized with labels like TWO MODES, RESPONSE, and SAFETY FIELDS. It front-loads the core purpose and mode selection before moving to output details and caveats, and every sentence earns its place.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: leg prices, spreads, compatibility warnings, codes, skipped comparisons, temporal alignment, and low-confidence pairs. It also sets realistic expectations about the tool's current reliability.

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

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

Schema description coverage is 100%, so the schema already documents every parameter. The description adds value by framing the two modes, explaining that topic shortcuts auto-fetch matching events, and clarifying that explicit tickers enable custom pairings. This exceeds the baseline without being redundant.

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 purpose—computing the cross-venue spread between Kalshi and Polymarket for the same resolving question—and clearly separates this from related concepts like arbitrage or tradeability. It is immediately identifiable against sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description gives clear context on when to use the tool, explains both invocation modes, and warns that pre-mapped topics are often not tradeable. It does not explicitly name alternative sibling tools or say 'use X instead when Y', so it falls just short of a full 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the return-value composition (character, name, category, group) but does not disclose additional behavioral traits such as whether the random selection is truly uniform or whether repeated calls can return duplicates. Since annotations are robust, a baseline 3 is appropriate.

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

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

The description is two sentences long, front-loaded with the core action and output fields, followed by a single usage sentence. No wasted words or redundant content.

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

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

This is a simple tool with no parameters, a clear output schema (not shown but noted as present), and robust annotations. The description fully covers what the tool does, what it returns, and when to use it. There are no gaps requiring additional detail.

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

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

The tool takes no parameters (schema has zero properties and 100% coverage). The description adds no parameter-specific details because none exist. Per calibration guidelines, zero-parameter tools earn a baseline of 4, and the description fulfills this by not inventing unnecessary parameter information.

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

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

The description clearly states the action ('Get a random emoji') and the resource ('emoji'), and specifies the returned fields: character, name, category, and group. It distinguishes itself from sibling tools like get_by_category or get_by_group by emphasizing randomness, making its unique purpose unmistakable.

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

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

The description provides explicit when-to-use guidance: 'Use when you need an unpredictable emoji for variety or surprise elements.' It does not explicitly contrast with deterministic alternatives like get_by_category, but the context is clear enough for most use cases, earning a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable behavioral context: scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the list-all-keys behavior when the key is omitted. 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 three sentences, each with a clear purpose: function, use cases, and scoping/relationships. It is front-loaded with the primary action and contains no filler or redundant restatement of the schema.

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

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

For a simple, one-optional-parameter tool with robust annotations and a clear schema, the description provides sufficient context for selection and invocation. It explains both retrieval and listing modes. It does not specify return format or missing-key error behavior, but this is not critical given the simplicity and the presence of an output schema (or lack thereof).

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

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

Schema coverage is 100% and the property description already explains the 'omit to list' behavior. The description enriches this with concrete examples of keys (user's target ticker, address, prior research notes) and reinforces the meaning of 'key' as a previously saved memory key, adding value beyond the schema.

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

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

The description uses a specific verb ('Retrieve') and resource ('a value previously saved via remember') and clearly distinguishes two modes: retrieving a single value and listing all keys. It also positions the tool relative to sibling tools by naming remember and forget, making the purpose unambiguous.

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

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

The description explicitly states when to use the tool ('Use to look up context the agent stored earlier') and provides a clear contrast to re-deriving information. It mentions paired tools (remember to save, forget to delete), but does not include explicit exclusionary criteria or alternatives for other lookup 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?

The annotations declare readOnlyHint: true, but the description discloses that setting mark_read:true flags events as read, which is a state modification. This directly contradicts the read-only annotation, so the score is 1.

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

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

The description is remarkably concise, using two sentences to cover functionality, return value, filtering, state mutation, and an alternative access method. No filler words 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?

The tool has 5 optional parameters, no output schema, and annotations. The description explains the return payload, filtering options, mark_read side effects, and even provides a public endpoint for scripts. Combined with schema coverage, it leaves little ambiguity.

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

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

With 100% schema coverage, the baseline is 3. The description adds contextual examples like 'sec_8k' and explains the consequence of mark_read, which enriches parameter semantics. This justifies a score of 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 subscription feed and describes the return payload. It uses specific verbs and distinguishes it from sibling tools like recent_changes by focusing on alerts. The mention of source, citation_uri, and raw event payload makes the purpose explicit.

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

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

It provides clear context on when to use the tool, including polling and filtering. It also offers an alternative HTTP endpoint for scripts/dashboards, which helps differentiate from using the tool directly. However, it does not explicitly state when not to use it compared to other 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?

The description discloses source fan-out to SEC, GDELT→GNews fallback, and USPTO soft-fail due to PatentsView sunset, which goes beyond the readOnly/idempotent annotations. It also describes the return shape (changes[], total_changes, 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 dense but every sentence contributes: examples, sources, fallback behavior, date formats, return structure, and alternative tool. 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?

Despite lacking an output schema, the description covers the key return fields, source behaviors, date parsing, and when to use the alternative. It is complete for a complex multi-source tool with good annotations.

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

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

Schema coverage is 100% and the schema already explains `since`, `value`, and `type`. The description partly repeats `since` syntax but adds no new parameter meaning; 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 clearly identifies the tool as a change feed for a company over a temporal window, listing concrete example queries and explicitly contrasting with entity_profile for static profiles. This makes the purpose unambiguous and distinguishes it from siblings.

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 usage context via example queries ('What's new with X') and an explicit alternative: 'Use entity_profile instead when you want the static profile...' This tells an agent when to choose another tool.

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

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

The description goes well beyond the provided annotations by disclosing the storage as key-value pairs scoped by the agent's identifier, persistence for authenticated users, and a 24-hour retention window for anonymous sessions. This adds meaningful behavioral context that annotations alone do not convey, and nothing contradicts the readOnly/idempotent/destructive hints.

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

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

The description is efficiently structured with a front-loaded purpose, followed by use-case examples, storage semantics, retention behavior, and related tools. Each of the five sentences contributes unique information without redundancy or 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 tool with no output schema and good annotations, this description covers purpose, when to use, storage scope, persistence behavior, and how to retrieve or delete later. It provides sufficient context for reliable invocation, and the only minor question about overwriting is reasonably implied by 'save' and idempotentHint.

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

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

The input schema already provides full descriptions and examples for both key and value, covering 100% of parameters. The description only refers generically to a 'key-value pair' and does not add additional parameter-level detail, so it sits at the baseline for high schema coverage.

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

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

The description opens with a specific action and resource: 'Save data the agent will need to reuse later,' spanning conversation and cross-session persistence. It clearly differentiates itself from sibling tools recall and forget by framing this as the storage operation, with retrieval and deletion explicitly assigned to those siblings.

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

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

Explicitly instructs when to use: 'Use when you discover something worth carrying forward,' with concrete examples like resolved tickers and user preferences. It also gives direction for companion tools: 'Pair with recall to retrieve later, forget to delete,' effectively describing the usage context relative to alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant value: cascading internal lookups, graceful degradation when GLEIF/OpenFIGI unavailable, explicit listing of unresolved identifiers, and source labeling. 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 fairly long but well-structured with front-loaded examples and clear sections for each type. Every sentence provides useful information. Slightly verbose but justified by the coverage needed to explain the complex behavior.

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

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

Given the moderate complexity (2 parameters, no output schema), the description covers return behavior (identifiers with source labels, unresolved listed), error handling (graceful degradation), and use cases. It could have described the exact response structure, but the mention of identifiers and unresolved is sufficient.

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

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

Schema description coverage is 100% (both parameters have descriptions). However, the description enriches the schema significantly: for 'type' it details what each type returns, and for 'value' it lists accepted formats (ticker, CIK, ISIN, name for company; brand/generic for drug). This adds meaning beyond the basic 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 resolves names to canonical identifiers, with specific examples like 'What's the ticker for...' and lists supported types (company, drug). It distinguishes itself from sibling tools by emphasizing that it provides identifiers needed as input for other 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?

Explicitly says 'Use FIRST whenever you have a name but need an ID.' It also implies when not to use (if you already have an ID) and explains that it replaces 2-3 manual lookups. Could be 5 if it explicitly stated 'do not use if you already have the identifier' but it's clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds behavioral value by disclosing it probes with ai_visibility_check, ranks by score, and returns a ranked list with specific fields (score, confidence, signal density), which goes beyond the annotations.

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

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

The description is three sentences with no filler: it states the main action, the method (probing with ai_visibility_check), a concrete use case, and the output shape. Every sentence contributes meaning, and the core comparison action is front-loaded in the first sentence.

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 states the return format ('ranked list with score, confidence, signal density per entity'), which gives the agent a clear expectation. It omits details like model selection and API key nuances, but those are captured in the input schema, making the description sufficient for an initial understanding.

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 all parameters are already well-explained in the input schema. The description adds no new parameter-level details; it only paraphrases the 'entities' concept ('your brand + N competitors') without introducing semantics beyond the schema.

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

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

The description opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It further distinguishes itself from the sibling ai_visibility_check by stating it probes each entity with that tool and ranks by score, making the comparative scope clear.

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 with 'Useful for competitive AI-marketing audits' and gives a concrete question example. It does not explicitly exclude alternatives, but the reference to 'with ai_visibility_check' implies the single-entity case belongs to that sibling tool, making the usage context clear.

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

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

The description adds significant behavioral context beyond the annotations: it discloses that the tool fans out to multiple sources, that partial failures degrade gracefully, that bundlephobia's first measurement on a new version can take 5–30 seconds, and that sources_failed will list timeouts. This is valuable and does not contradict the readOnlyHint=true annotation.

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: main purpose, usage triggers, return summary, ecosystem scope, and failure behavior. It is front-loaded with the core function and structured logically, making it easy to scan.

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

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

Despite having no output schema, the description enumerates the summary block fields, per-advisory detail, links, and alternative versions. It also covers ecosystem limitations and partial failure behavior, providing a complete picture for an agent to use the tool effectively.

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

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

The input schema already provides 100% coverage, describing 'package' as an npm package name with scoped package support and 'version' with default behavior. The description reinforces these but adds no new parameter-level semantic details beyond what the schema offers, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as a composite check for npm packages, combining deps.dev and bundlephobia data. It specifies the verb ('check'), resource ('npm package'), and the exact outputs, distinguishing it from all sibling tools, none of which cover dependency scanning.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives a direct alternative for non-NPM ecosystems: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', which is a clear exclusion.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description reveals significant behavioral traits: uses 'BGE-base-en embeddings + cosine over 500-char overlapping windows,' enforces a 'cap is 200K chars' with truncation and flagging, and describes output as 'passages with character offsets and similarity scores.' This is exactly the kind of operational detail annotations do not capture.

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

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

The description is front-loaded with the core purpose in the first sentence, then methodically covers usage, pairing, and technical details. Each of the five sentences earns its place — no filler. It is slightly longer than the ideal two-sentence example, but the complexity of the tool justifies the extra sentences.

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

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

Given no output schema, the description adequately explains return values ('top-N passages with character offsets and similarity scores'), operational limits (200K cap, truncation flag), and the integration workflow with ask_pipeworx_grounded. It covers all essential aspects a caller needs to know: when to use, how it works, what it returns, and its constraints.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving real-world examples for both text and query: 'a SEC 10-K body, an article, a long tool result' and query examples like 'supply-chain risk' and 'drug interactions with warfarin.' These examples clarify the intended usage better than the schema descriptions alone.

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

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

The description opens with a specific verb-resource pair: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from siblings by explicitly pairing with ask_pipeworx_grounded and explaining that it operates on already-pulled text, not whole documents. The examples of record types (SEC 10-K, article, long tool result) further clarify scope.

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

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

Provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter.' It also names a specific complementary tool (ask_pipeworx_grounded) and the recommended workflow ('fetch with the gateway, ground over the relevant passages'), giving clear alternatives and integration context.

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

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

Beyond the annotations (idempotent, non-read-only), the description discloses OAuth account requirements, the always-on feed behavior, optional delivery channels, SMS verification and caps, and webhook auto-disable after 10 consecutive failures. This adds significant 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 densely informative yet well-structured: purpose, requirements, types, then delivery channels. No sentence is redundant or filler; each adds necessary details for correct invocation.

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

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

For a tool with no output schema and nested parameters, the description covers purpose, supported types, delivery options, authentication prerequisites, and return value. It leaves few gaps, making it highly complete for an agent to select and invoke correctly.

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

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

The schema already provides 100% coverage with examples for each type and delivery option. The description reinforces these and adds the OAuth account requirement and feed channel context, but the schema carries the primary parameter semantics.

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

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

The description clearly states the verb ('Create') and resource ('proactive monitoring subscription to a live-data event stream'), and explicitly mentions the returned subscription id. This distinguishes it from siblings like list_subscriptions and unsubscribe by focusing on the creation 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 explains when to use the tool (to receive alerts), prerequisites (OAuth account, verified phone for SMS), and delivery channels. However, it does not explicitly name alternative tools for viewing or removing subscriptions, so it stops short of full alternative 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 provide readOnly, idempotent, and openWorld hints. The description adds value by explaining that it returns example questions with exact tool+argument shapes from the live catalog, and that omitting the topic gives the full spread while passing a topic focuses results. This is useful behavioral context beyond the annotations.

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

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

The description is long with many example utterances, but they serve an onboarding purpose and are front-loaded. It is well-structured and every part contributes, though it could be trimmed slightly without losing value.

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

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

There is no output schema, but the description clearly states the return shape (category-bucketed example questions with exact tool and argument shape) and explains both invocation modes. For a read-only tool with one optional parameter, this is completely sufficient 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 documents the optional topic parameter with 100% coverage, so the baseline is 3. The description adds concrete examples ('finance', 'pharma', 'betting') and clarifies the omit-for-full-spread behavior, providing meaningful extra guidance 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 this as the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape. It distinguishes itself from siblings like discover_tools by focusing on what Pipeworx can do and how to call meta-tools, and it lists concrete trigger phrases that make the purpose unmistakable.

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

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

The description explicitly says to use this FIRST when you don't know what Pipeworx can do, and it names meta-tools to learn. It lacks an explicit when-not-to-use statement, but the 'FIRST' guidance gives clear ordering, so it earns a 4 rather than a 5.

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

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

Beyond annotations (destructiveHint=false), the description adds valuable behavioral context: the row is deactivated not deleted, so historical events remain available via recent_alerts. It also discloses the ownership authorization requirement, which is not inferable from 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, front-loaded with the action. Each sentence provides essential information: the operation and the behavioral nuance. No waste or redundancy.

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

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

For a low-complexity tool with one parameter and no output schema, the description covers the key aspects: purpose, ownership, deactivation behavior, and where historical data stays visible. It is self-sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the parameter 'id' is fully described as 'Subscription id (uuid) returned by subscribe.' The description only says 'by id' without adding new semantics, meeting the baseline for a well-documented 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 clearly states the tool cancels a subscription by id, with a specific verb and resource. It distinguishes itself from siblings like subscribe and list_subscriptions by emphasizing ownership enforcement and deactivation (not deletion), which sets it apart from a generic delete 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?

It provides clear context: cancel your own subscription by id. Ownership enforcement is explicitly stated, indicating when this tool cannot be used (others' subscriptions). It doesn't explicitly name alternatives, but the context is sufficient to know when 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?

The description adds substantial behavioral context beyond the annotations' read-only/open-world hints. It discloses the exact verdict types (confirmed, approximately_correct, refuted, inconclusive, unsupported, could_not_verify), explains that could_not_verify means the check failed (not evidence), includes the verification_error structure, and defines unsupported as 'no source exists'. It also reveals routing behavior and the tolerance override, all valuable for correct interpretation of results.

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

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

The description is dense but well-structured: it opens with trigger phrases, then states the use case, explains routing, return values, and ends with important caller caveats and the efficiency benefit. Every sentence adds unique information, though the single long paragraph with semicolons and dashes could be slightly more scannable. It is appropriately sized for a complex tool with nuanced behaviors.

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 (two routing paths, six verdict types, error semantics) and the lack of an output schema, the description is remarkably complete. It explains return values (verdict, actual value with citation, reasoning), distinguishes edge cases, and integrates with the full usage flow. Combined with the input schema and annotations, an agent has enough to select and invoke this tool correctly without any obvious gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context for 'tolerance_pct' by explaining it overrides the implied tolerance and giving a concrete use case (set 1–2 for hallucination detection). It also provides realistic example claims that illustrate the 'claim' parameter. This extra guidance justifies an above-baseline score.

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

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

The description clearly identifies the tool's purpose: verifying natural-language factual claims against authoritative sources using specific verb phrases like 'fact check' and 'verify the claim that'. It distinguishes itself from generic research or search tools by explaining the two-path routing (SEC EDGAR for company-financial claims, grounded pipeline for others) and explicitly stating it replaces a 4–6 step sequential process.

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

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

The description gives explicit guidance on when to use: 'Use whenever the agent needs to check whether something a user said is factually correct', with many example query phrasings. It also explains internal routing based on claim type and notes it replaces multiple sequential calls, implying it should be preferred over orchestrating separate steps. However, it does not name any sibling tools as alternatives or state when NOT to use it, so it lacks explicit exclusions.

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