genderize

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds key behavioral context: the default model is free Workers AI Llama-3.3-70b, probing Anthropic requires a user-supplied _apiKey with direct billing, and the return structure includes per-model score, confidence, signals, raw_response, and a combined view.

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

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

The description is three sentences long, front-loading the core purpose and then providing essential details on models, API key, and return values. Every sentence earns its place without any fluff or repetition of schema 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?

Even without an output schema, the description specifies the per-model return object and combined view, covers default vs. custom model selection, and gives usage context. Combined with thorough schema parameter docs and annotations, the tool is fully specified 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?

The schema covers all 4 parameters with descriptions (100% coverage). The description adds valuebeyond the schema by explaining the default model behavior, the _apiKey billing implication, and the output format, which helps the agent understand parameter roles without re-reading the schema.

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

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

The description clearly states the tool probes LLMs for what they know about a business/brand/product/topic and scores visibility (0-100) per model. This specific verb+resource+output scope distinguishes it from sibling tools like ask_pipeworx or scan_competitor_ai_presence.

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 lists concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and mentions the default model and BYO-key requirement. It does not explicitly contrast with alternative siblings, but the context is clear enough for an agent to decide 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?

Annotations already declare readOnly/int idempotent and non-destructive. The description adds valuable behavioral context: routing to 5,529 tools, filling arguments, returning structured answers with stable citation URIs, and stating it works on every tier with one fast call. No contradictions with annotations.

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

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

The description is long but well-structured: it front-loads the preferred usage, then explains capabilities, gives explicit trigger examples, and ties to alternatives. Each sentence adds useful information, though some redundancy exists (e.g., 'PREFER OVER WEB SEARCH' and 'START HERE' both emphasize default use).

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

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

Given the tool's complexity and lack of output schema, the description provides a comprehensive overview of scope, examples, and alternatives. It covers major domains and mentions citations. It could mention edge cases or error handling, but overall it is sufficient for an agent to decide when to use it.

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

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

Schema coverage is 100% with descriptions for all six parameters (mostly aliases). The description adds contextual examples of question types but does not provide additional parameter-level semantics beyond what the schema already states. 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 that ask_pipeworx routes questions to the right one of 5,529 tools and returns structured answers with citation URIs. It distinguishes itself from siblings by explaining it is the default entry point and explicitly mentions grounded and deep_research as alternatives.

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

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

The description gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE'), specific trigger phrases, and clearly lists alternatives with conditions ('Step up only when needed: for ... use ask_pipeworx_grounded; for ... use deep_research'). It also covers breaking-news use cases.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, non-destructive), the description adds valuable behavioral context: it is a full working router with no fallback, candidate routing improvements are enabled live only when under test, and currently no candidate is active so it matches ask_pipeworx exactly. This clarifies the experimental nature and current state.

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

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

The description is three sentences long and front-loads the core identity, followed by current status and usage. While detailed, every sentence contributes necessary context (beta identity, current inactivity, usage guidance, no-fallback guarantee). It is slightly wordy but still efficient.

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

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

For a complex routing tool with no output schema, the description provides essential context: identity relative to ask_pipeworx, experimental behavior, current parity with stable, usage instructions, and comparison purpose. It sufficiently explains what to expect without needing to enumerate the router's internal mechanics.

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 is comprehensive with 100% coverage: all six parameters are documented as aliases for 'question', and 'question' has a clear description. The description adds no extra parameter semantics, just says 'same arguments' as ask_pipeworx. Since schema already covers parameter meaning, baseline 3 is appropriate.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge with candidate routing improvements.

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 this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also references the stable router as the comparison baseline, implying that for non-experimental needs one would use the stable version. However, it does not explicitly list alternative tools beyond 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?

Beyond the readOnly/idempotent annotations, the description discloses the refusal mechanism with specific reasons, states it uses ONLY the tool result, lists the exact return fields, and notes the extra LLM cost. This is rich behavioral context that helps the agent predict outcomes and failure modes. No contradiction with annotations.

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

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

Though longer than typical, every sentence carries critical information: purpose, routing mechanism, return contract, refusal modes, use cases, and cost tradeoff. It is front-loaded with the key phrase and structured to quickly convey when to use it. No filler.

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

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

With no output schema, the description fully specifies the return object (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal reasons. It also explains the underlying routing behavior and the cost/benefit tradeoff, making the tool's behavior predictable in context despite missing 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?

The schema already covers all 6 parameters with descriptions (aliases for question) at 100% coverage, so the description adds no new parameter meaning. The description mentions 'fills arguments' generically but does not elaborate on the question parameter. Baseline 3 is appropriate because schema does the heavy lifting.

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 this is a 'hallucination-resistant answer mode for high-stakes reads' and contrasts it with ask_pipeworx, explicitly distinguishing its behavior (extract answer using only tool result, return evidence) from the sibling. The verb 'extracts' plus the resource scope (grounded answers) makes the purpose unmistakable.

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

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

It explicitly says when to use ('whenever an answer will be quoted, cited, or acted on') and when not ('prefer ask_pipeworx for casual lookups'). It also names the alternative tool and explains the cost tradeoff (one extra LLM call), giving clear context for choosing between siblings.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes far beyond these by detailing the resolver contract (market_match_confidence, market_match_score, alternatives, suggestions), safety short-circuiting ('status:"low_confidence_match"'), closed-market handling ('status:"market_closed_or_inactive"'), wide-spread tradeability notes, and cancellation-rule parsing (refund_50_50, resolves_no_on_cancel, etc.). This richly discloses behavior without contradicting annotations.

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

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

The description is long but information-dense, with the main purpose front-loaded and logical sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, RESOLUTION-RULE RISK). Every sentence earns its place, though it could benefit from more visual structure (headings) to break the wall of text. Still, it's appropriately sized for a tool of this complexity.

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

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

For a complex tool with no output schema, the description thoroughly covers input flexibility, response shapes (result.market, result.analysis, result.evidence), resolver fallback behavior, parent-event extraction, news fallback fields, and resolution-rule risk. It also warns about low-confidence matches and closed markets, leaving no significant gap for an agent to misuse the tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds substantive meaning: it clarifies the market parameter accepts a slug, URL, or question text; explains depth 'quick' vs 'thorough' fan-out; and for include_raw quantifies response sizes ('keeps responses under ~20KB' vs '50KB-500KB') and when to pass true. These details go beyond the schema's own descriptions, adding practical guidance.

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

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

The opening sentence—'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call'—uses a specific verb ('research') and resource ('Polymarket bet' + 'Pipeworx data'), clearly distinguishing it from siblings like ask_pipeworx (general Q&A) and deep_research (broad research). The description also gives concrete examples and classifiers, reinforcing its unique niche.

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

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

Explicit use cases are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also includes important guidance like 'ALWAYS inspect these before trusting the analysis block' and 'Check this before sizing sports/esports/event-occurrence bets'. However, it does not explicitly name alternative sibling tools or state when NOT to use this tool, so it lacks full when/when-not clarity.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds substantial context: type-specific data sources (SEC EDGAR/XBRL, FAERS), fiscal-year handling, result sorting by primary metric, and return format with citation URIs. This goes well beyond annotations and clearly sets behavioral expectations.

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

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

The description is longer than the calibrated high example but remains front-loaded with trigger phrases and key guidance. Every sentence adds value, though the 'Replaces 8–15 sequential lookups' clause is somewhat redundant with the ALWAYS PREFER statement. It is dense but not padded.

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 properly explains return values (paired data + citation URIs) and sorting behavior. It covers both entity types, data sources, and edge cases like off-calendar fiscal years, making it complete for a tool of moderate complexity.

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

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

Schema coverage is 100%, so the schema already documents type and values. The description adds meaningful beyond-schema details such as the 2–5 range, example tickers/drug names, and the fact that results are sorted by primary metric, which helps interpret values. However, it does not add much about parameter syntax beyond examples.

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

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

The description explicitly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one call, using clear trigger phrases like 'X vs Y' and 'which is bigger.' It distinguishes itself from sequential single-entity lookups and sibling tools like entity_profile by focusing on multi-entity comparison.

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

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

The description gives explicit when-to-use guidance with example queries and an 'ALWAYS PREFER' directive over sequential single-pack lookups. It also clarifies type-specific usage for company vs drug, but does not name specific alternative tools, which is a minor gap.

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

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

Despite annotations already marking it read-only/idempotent, the description adds substantive context: account prerequisites, output packet structure with gaps[] that are never invented, contradictions[], citation_uri fetchability, semantic excerpting, and time expectations. It also warns about empty gaps for non-structured topics.

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?

Long but every section earns its place — prerequisites, alternatives, output details, depth semantics, and timing are all relevant. It's front-loaded with the account requirement and core purpose, though it could be trimmed slightly.

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

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

For a tool with no output schema, the description fully covers the findings packet, gaps, contradictions, citations, hop fields, and performance expectations. It also addresses failure modes (empty gaps) and account constraints, making it complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the schema already thoroughly documents question and depth. The description repeats some depth behavior and adds example questions, but doesn't materially extend the schema's parameter descriptions.

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

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

Clearly states it performs grounded multi-source research across Pipeworx's 1455 structured data sources in one call, decomposing questions into facets and routing to 5,529 tools. Distinguishes from siblings by noting it is NOT open-web search and contrasts with ask_pipeworx for single 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?

Explicitly says to use for broad/multi-part questions over structured data, and to use ask_pipeworx for single lookups or breaking news topics. Also states if not signed in, use ask_pipeworx instead, giving a clear decision tree.

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

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

Annotations already establish it as a safe, read-only, idempotent operation. The description adds meaningful behavioral detail about the return format (top-N tools, names, descriptions, full schemas, curated examples) and that results are directly callable. 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 well-structured and front-loaded with the core purpose, followed by usage contexts, return behavior, and a clear recommendation to call first. Every sentence adds value, and the domain list is relevant but not redundant. It is appropriately sized for the information conveyed.

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 compensates by explaining what will be returned (top-N tools with names, descriptions, and full input schemas) and how to use the results directly. It covers the essential context for a meta-tool with six parameters, though it could briefly mention the response structure more explicitly.

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

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

The input schema has 100% description coverage, including aliases and constraints for 'limit'. The description itself adds little beyond the schema's already thorough parameter documentation, so it meets the baseline but does not elevate it.

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

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

The description explicitly states 'Find tools by describing the data or task' with a specific verb and resource, and lists many example domains. It clearly distinguishes itself from its research-oriented siblings by positioning itself as the meta-tool for discovering tools, not performing the tasks directly.

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 you need to browse, search, look up, or discover what tools exist...' and 'Call this FIRST when you have many tools available and want to see the option set.' It stops short of naming alternative tools or explicit when-not-to-use scenarios, hence not a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable detail: it fans out across multiple sources, lists exact return fields, mentions soft-fail for patents, and notes GDELT→GNews fallback, going beyond annotation coverage.

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

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

The description is long but every sentence contributes: usage examples, return fields, alternatives, fallbacks, and caveats. It is front-loaded with typical queries and ends with explicit input constraints, making it useful though somewhat verbose.

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

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

For a complex multi-source tool without an output schema, the description comprehensively covers inputs, outputs, error handling (soft-fail), fallback behavior, and limitations. No critical gaps remain for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by reinforcing the ticker/CIK format with concrete examples ("AAPL", "0000320193") and explicitly stating that names are unsupported, which aligns with the schema and clarifies usage.

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: 'full cross-source profile of a US public company' with examples like 'Tell me about X'. It distinguishes itself from sibling tools by explicitly preferring this over chaining SEC/XBRL/news lookups for holistic views.

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

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

Provides explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic requests. Also specifies when not to use it (names not supported) and directs users to resolve_entity first if only a name is available.

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 destructive and idempotent behavior, so the bar is lower. The description adds minimal extra behavioral context beyond the core delete action. It mentions 'previously stored' which implies the key must exist, but does not disclose error handling, return values, or what happens if the key is missing. Since annotations cover the main safety profile, a score of 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 concise and well-structured. It opens with a clear purpose statement, follows with practical usage scenarios, and ends with a note about complementary tools. Every sentence earns its place, with no redundant or filler 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?

For a simple tool with one parameter, full schema coverage, and clear annotations, the description is complete. It explains what the tool does, when to use it, and how it fits with related tools. No output schema exists, so no return value explanation is needed. The description adequately covers all necessary 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 schema provides 100% coverage with a clear description for the 'key' parameter ('Memory key to delete'). The description simply restates that deletion is 'by key' without adding details about key format, constraints, or examples. As the schema already documents the parameter fully, the description adds minimal extra value, aligning with the baseline of 3.

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

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

The description clearly states the tool's function: 'Delete a previously stored memory by key.' It uses a specific verb (Delete), identifies the resource (memory), and specifies the mechanism (by key). It also distinguishes itself from sibling tools by mentioning pairing with 'remember' and 'recall', making its role in the memory workflow 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?

The description provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' This clearly indicates the appropriate conditions for invoking the tool, though it does not explicitly mention when not to use it, the positive usage scenarios are well-defined.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value by detailing the process: fetching the page, extracting title/description/key links, and emitting the standard llms.txt markdown format.

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, and includes a practical output note. Every sentence earns its place with 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?

The tool is simple (2 params, no nested objects), and the description covers its purpose, output format, and use cases. No output schema exists, but the description's statement about the output being a single text blob suffices for this low-complexity tool.

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

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

The schema describes both parameters completely (100% coverage), and the description does not add additional parameter semantics beyond what the schema already provides. Therefore, a baseline of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with a specific verb and resource. It also outlines the extraction and output steps, distinguishing it from sibling tools like ai_visibility_check.

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

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

The 'Useful for' section provides three concrete scenarios, giving clear context for when to use the tool. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds the 'caller's' scope and the list of returned fields, which is useful behavioral context beyond annotations. 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 three sentences, each serving a purpose: state the action, list return fields, and provide usage guidance. It is front-loaded and free of fluff.

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

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

For a simple list tool with one optional parameter, strong annotations, and no output schema, the description covers the action, return content, and typical use cases. It is complete enough for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% for the single parameter include_inactive, so the schema fully explains it. The description does not add parameter-level detail, but the baseline of 3 applies since the schema carries the load.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It also enumerates the returned fields, which further clarifies what the tool does. This distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

The description provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It implies when to use the tool but does not explicitly exclude alternatives or name sibling tools.

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

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

Annotations are all false, so the description carries the full burden. It discloses the claim_token workflow ('Filing without an account returns a claim_token; pass it back later...'), rate limiting ('Rate-limited to 5 per identifier per day'), quota behavior ('Free; doesn't count against your tool-call quota'), and that the team reads digests daily. This provides rich behavioral context beyond the annotations.

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

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

The six sentences are tightly packed with purpose, use cases, exclusions, composition rules, claim_token flow, and limits. No filler. It is structured logically, front-loaded with the core action, and appropriately sized for the tool's complexity.

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

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

Despite having no output schema, the description covers return behavior (claim_token), rate limits, exclusions, and composition constraints. It fully equips an agent to decide when to call, how to format the request, and what to expect back, making it complete for this tool's 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 coverage is 100%, so the baseline is 3. The description adds meaningful extra semantics: the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and a message constraint ('don't paste the end-user's prompt') not present in the schema. This elevates it above the baseline.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' a specific verb+resource pair. It explicitly limits the tool to 'tools served by this Pipeworx connection' and distinguishes from siblings by excluding other MCP servers. Listing concrete feedback categories (bug, feature/data_gap, praise) makes the purpose unmistakable.

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

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

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

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint false), the description discloses that the signal is self-aggregating from the CF analytics-engine, contains no PII, and is cached for 5 minutes to 1 hour depending on the window. This adds meaningful behavioral context without contradicting any 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 structured and front-loaded: opening with the core purpose, then the return value, followed by numbered use cases, and ending with data provenance and caching. Every sentence contributes useful information without fluff, making it both concise and well-organized.

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

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

Even though there is no output schema, the description explicitly says what is returned (top tools, top packs, total call volume), plus data source, privacy, and caching behavior. This is complete for a simple read-only tool with one optional parameter, and it fits well within the sibling 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 schema already describes the 'window' parameter with enum values and their meaning (shorter windows for hot right now, longer for steady-state). The description adds that caching duration depends on the window, providing extra value beyond the schema, which merits a 4 given the high schema coverage.

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

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

The description clearly states what the tool does: it reports what other AI agents are calling on Pipeworx, returning top tools, top packs, and total call volume over a recent window. The verb 'returns' plus specific resource and scope make the purpose unambiguous and distinguish it from siblings like discover_tools or ask_pipeworx.

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

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

The description provides three explicit 'Useful for' scenarios: discovering hot data sources, confirming canonical tool choice before asking, and checking alignment with common agent needs. This gives clear context, though it doesn't explicitly mention alternatives or when not to use it, so it's just 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?

Discloses key behaviors beyond the readOnlyHint/idempotentHint annotations: partition filter (drops placeholder slugs, null signal if >20% placeholder), fill check pricing against live CLOB depth, and the critical caveat that realizable_edge_pp ≤ 0 means do not trade. These are valuable operational details.

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 lengthy but excellently structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence carries information relevant to selection and invocation; no filler or tautology.

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 explicitly lists the response structure (opportunities[], partition_check{...}) and covers edge cases (fill check, placeholder filters, low similarity). It also cross-references polymarket_fill_risk for sizing, making it effectively complete for this complex tool.

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

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

Even though schema coverage is 100%, the description adds substantial context: concrete examples for 'event' (e.g., 'fed-decision-may-2026') and 'topic' (e.g., 'Strait of Hormuz traffic returns to normal'), mentions that full Polymarket URLs are accepted for event, and clarifies the exact scope of each parameter mode.

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 this tool from siblings by its method (monotonicity + partition checks) and enumerates three modes (trending_scan, event, topic).

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

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

Provides explicit guidance: 'Call with NO args for a trending_scan', recommends event for a specific market, and topic for cross-event scanning. Also directs users to a sibling tool, polymarket_fill_risk, for custom sizing, making the when-to-use vs. alternatives 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?

Goes far beyond the readOnly/openWorld/idempotent annotations by disclosing caching behavior ('Cached 1h at the KV level'), detailed internals (model families, slippage handling, placeholder-slug filters, funnel diagnostics), and caveats (Fed data unreliability, rare longshots, 24h-move warnings). This is rich behavioral context that materially helps an agent understand side effects and limitations.

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

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

The description is long, but densely packed with essential information and organized into labeled sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, RESPONSE TOP-LEVEL). Every sentence contributes substance; the length is justified by the tool's complexity, though it could be slightly tightened for easier skimming.

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 the response structure (by_segment, fed_candidates/fed_note, _diagnostics) and explains why segments might be empty. It covers edge cases, knob effects, and caching. This is a complete picture for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with detailed per-parameter descriptions. The tool description adds value by grouping parameters into 'TRADEABLE-EDGE KNOBS' and explaining interplay (e.g., why min_kelly doesn't filter partition arbs but min_partition_leg_kelly does). This goes beyond the schema's isolated parameter descriptions, though the schema already does heavy lifting.

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 ('Scan top Polymarket markets and return opportunities') and clearly distinguishes itself from siblings by referencing Pipeworx data disagreement and the three model families. The user intent ('what should I bet on today') is explicit, leaving no doubt about the tool's function.

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

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

Clear context is given: the tool is built for discovering betting opportunities without paging hundreds of markets, and it explains the tradeable-edge knobs (min_liquidity, max_spread_pp) that alter filtering behavior. However, it does not explicitly name alternative tools or state when NOT to use this tool versus siblings, so it falls short of a 5.

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

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

Given the annotations already mark the operation as read-only and idempotent, the description adds considerable extra behavioral detail: 60-day TTL history limit, snapshots written on cache-miss, gaps meaning no scan, and decay computed from daily closes rather than intraday. This goes well beyond the annotations and prepares the user for data freshness and edge cases.

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

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

The description is lengthy but well-structured with clear ARGS/RESPONSE/LIMITS sections. Every sentence conveys operational necessity, though the opening uses a rhetorical flourish that could be trimmed. The structure helps an agent parse it efficiently.

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 the return structure (tracked, expired, snapshot_dates), including field meanings and computation logic. It also covers limitations and data provenance. This is complete for a telemetry tool of this complexity.

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

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

The input schema already provides full descriptions for both parameters (100% coverage), so the baseline is 3. The description restates defaults and the 'window' concept but adds no meaningful new detail; in fact, it slightly conflicts with the schema by saying 'max 30' while the schema says 'clamp 2-30'.

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 a specific function: edge persistence and decay telemetry formed from daily polymarket_edges snapshots. It distinguishes itself from sibling tools by focusing on the temporal dimension of edges rather than just current edge values, answering 'how long has this edge existed and is it shrinking?'.

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

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

The description provides strong contextual guidance by contrasting fresh vs. old edges and stating the questions it answers. However, it does not explicitly name alternative tools (e.g., polymarket_edges) or give exclusion criteria, so it falls just short of an explicit when-to-use vs. when-not-to-use directive.

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, non-destructive, idempotent behavior. The description adds substantial context: 'walks the ladder', returns slippage, VWAP, verdict, per-leg fill details, thin_legs[], and forced_directional_risk. It also warns about partial fill risks, offering depth beyond annotation hints. 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 highly structured: a one-sentence summary, then mode-specific details, then actionable usage guidance. Every sentence carries information; however, it could be tightened without losing key content, so it earns a 4 rather than 5.

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

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

Given the tool's complexity (two modes, four parameters, no output schema), the description is complete. It lists return fields for both modes, explains output semantics like capture_ratio and max_clean_notional_usd, and provides risk context. Nothing essential is missing.

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

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

Schema description coverage is 100% and each parameter already has detailed meaning (e.g., side defaults, size_usd interpretation). The tool description adds the one-of market/event constraint and restates mode-specific semantics, but does not significantly expand beyond the schema, so baseline 3 is appropriate.

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

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

The description states the tool's core function precisely: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) and explains each mode's inputs and outputs, which differentiates it from 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 explicitly instructs when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (theoretical overround on thin books is not capturable, partial basket fills create unhedged directional risk), providing clear exclusions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, and the description adds extensive behavioral context: compatibility_warning triggers, temporal alignment semantics, skipped_cross_type/subtype counters, and the honest limitation that most pre-mapped topics return warnings. 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 front-loaded and information-dense. Every section—modes, response anatomy, safety fields—serves a purpose given the tool's complexity, and the use of capitalized labels ('TWO MODES', 'RESPONSE', 'SAFETY FIELDS') improves scannability without wasted prose.

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

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

With no output schema, the description fully explains the response anatomy: leg-by-leg prices, matched spread, compatibility_warning, temporal_alignment, and skip counters. It also documents failure modes and when results are invalid, making the tool self-contained and reliable for an agent to invoke.

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

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

Schema coverage is 100%, but the description adds crucial meaning by explaining the topic shortcut list, auto-fetch behavior, and how explicit kalshi_event_ticker/polymarket_event_slug override the topic-mapped sides. This clarifies parameter interaction and expected values far beyond the raw schema.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this tool from venue-specific siblings like polymarket_arbitrage by emphasizing the cross-venue comparison and naming both platforms. This is a precise, non-tautological purpose statement.

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

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

The description explicitly details two modes (topic shortcuts vs explicit pairing) and when each is appropriate. It gives strong when-not guidance: compatibility_warning indicates no arb exists, temporal_aligned:false means spreads are meaningless, and 'pre-mapped ≠ tradeable' sets clear expectations. This goes beyond generic usage hints.

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 valuable context by specifying the return fields (predicted gender, probability 0–1, sample size) and the global data scope, going beyond the annotations without contradicting them.

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

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

The description is two sentences that efficiently state the action, scope, and output. It is front-loaded with the verb 'Predict' and contains no unnecessary words 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?

For a simple one-parameter tool with full schema coverage, annotations, and output schema, the description is complete. It explains the purpose, output structure, and global data scope, giving an agent everything needed to invoke it correctly.

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

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

The input schema fully describes the only parameter 'name' with the same information ('First name to predict gender for.'). The description does not add additional parameter semantics beyond what the schema provides, 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 states a specific verb and resource: 'Predict gender from a first name using global data.' The mention of 'global data' distinguishes it from the sibling tool predict_gender_country, making the purpose unambiguous.

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

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

The description provides clear context that this is for global data, implying it is not for country-specific predictions. However, it does not explicitly name alternatives or state when not to use it, 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 readOnly, idempotent, non-destructive behavior. The description adds value by stating the return fields (gender, probability, regional sample size) and confirming the country-specific scope, which are not covered by annotations.

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

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

The description is a single, focused sentence that front-loads the core purpose, followed by output details. Every word contributes value with no redundancy.

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

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

Given the simple two-parameter schema, rich output schema, and strong annotations, the description fully covers the tool's behavior and return values. No critical information is missing for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% with clear descriptions for both 'name' and 'country_code'. The description provides sample country codes but does not add semantic meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states a specific action ('Predict gender from a first name') and a specific resource ('in a specific country'), with examples. This distinguishes it from the sibling tool predict_gender, which likely lacks country-specific context.

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 phrase 'in a specific country' implies the tool is for country-aware predictions, which is useful context. However, it does not explicitly mention alternatives like the simpler predict_gender tool or state when not to use this variant, 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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds scoping to the user's identifier (anonymous IP, BYO key hash, or account ID), which is a meaningful behavioral detail 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 long, with the core function in the first sentence and supporting details (usage examples, scoping, pairing) in the following ones. There is no redundancy or filler; every sentence earns its place.

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

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

For a simple tool with one optional parameter, no output schema, and strong annotations, this description is complete. It covers both operational modes (retrieve by key, list all keys), scoping, and typical usage examples, leaving no critical gaps.

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

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

The single parameter 'key' is fully described in the schema: 'Memory key to retrieve (omit to list all keys)'. The description restates this but adds no new parameter-specific meaning. With 100% 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 opens with 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)', which precisely states the tool's function with a specific verb and resource. It distinguishes itself from siblings by explicitly naming remember (save) and forget (delete) as companions.

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

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

It explicitly says 'Use to look up context the agent stored earlier' and provides concrete examples, implying the alternative is re-deriving from scratch. It also names paired tools (remember, forget) for clear 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, so the safety profile is clear. The description adds valuable behavioral context by explaining the mark_read side-effect (flags events read so subsequent calls show only newer ones), the returned fields (source, citation_uri, raw payload), and the availability of an HTTP endpoint. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the core purpose in the first sentence. Each sentence earns its place: the first describes what it does, the second details returned fields and filtering, and the third covers mark_read, polling, and the alternative endpoint. No redundant or filler 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?

For a 5-parameter tool with no output schema, the description covers the key aspects: what is returned (source, citation_uri, raw payload), how to filter, the mark_read behavior, and polling suitability. It doesn't describe the full response structure or error scenarios, but the provided information is sufficient for an agent to correctly invoke the tool in most cases.

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 rephrases filtering by type and since, and provides a concrete example ('sec_8k'), but this adds little beyond the schema's existing parameter descriptions. No additional syntax, defaults, or edge cases are introduced.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Pull fired events from your subscription feed' and 'Returns the most recent alerts'. This distinguishes it from sibling tools like list_subscriptions or recent_changes by focusing on the alert feed and the evaluator's persisted 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?

The description gives usage context by noting 'Polls work fine' and provides an explicit alternative: 'the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' This implies using this tool for agent interaction and the HTTP endpoint for automated scripts. However, it doesn't explicitly compare to sibling tools like recent_changes, leaving some ambiguity.

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?

It discloses fan-out to SEC EDGAR, GDELT→GNews fallback rules, USPTO soft-fail due to API sunset, and return shape (changes[], total_changes, citation URIs) — all beyond the read-only/idempotent annotations. 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 element earns its place: examples, purpose, sources, fallback, date formats, return structure, alternative pointer. It's front-loaded and not padded, appropriate for 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 still explains the return structure (changes[] grouped by source + total_changes + citation URIs) and covers edge behavior (GDELT preferred, GNews fallback, soft-fail). For a multi-source tool with 3 params, this is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds a typical-monitoring recommendation ('Use "30d" or "1m"') and clarifies `since` semantics in context, but most parameter details duplicate the schema. This modest extra guidance merits 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 opens with concrete natural-language examples then immediately states 'change feed for a company in the last N days/weeks/months' — a specific verb+resource+scope. It distinguishes from the sibling by explicitly pointing to entity_profile for static profiles, making 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?

Beyond the purpose, it specifies when to prefer this tool over an alternative: 'Use entity_profile instead when you want the static profile ... regardless of window.' It also states this works in 'ONE parallel call' and details source fallback behavior, giving clear usage context. It doesn't list exclusions for every sibling but provides enough for the most relevant 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?

Beyond the annotations (idempotentHint, destructiveHint), the description discloses additional behavioral context: scoping by identifier, persistence differences between authenticated and anonymous sessions (24-hour retention), and the storage format. This gives the agent critical operational expectations not captured 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 four focused sentences, front-loaded with the primary purpose, followed by usage, storage details, and tool pairing. No verbose or redundant language; every sentence adds value.

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

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

For a simple two-parameter write tool with no output schema and limited annotations, the description covers purpose, usage, persistence semantics, and relationships to related tools. It fully equips the agent to decide when and how to call it.

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

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

Schema coverage is 100% with detailed descriptions for both 'key' and 'value'. The tool description adds usage examples but does not meaningfully change param semantics. Since the schema already carries the load, a baseline of 3 is appropriate.

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

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

The description opens with a clear action and target: 'Save data the agent will need to reuse later' combined with the storage model of 'key-value pair'. It directly differentiates from siblings by explicitly pairing with 'recall to retrieve later, forget to delete', which clarifies its role as the write operation in the memory trio.

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

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

Usage guidance is explicit: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference). It also names complementary tools (recall, forget), effectively communicating when to use this tool versus its siblings.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses several important behaviors: graceful degradation if GLEIF or OpenFIGI is unavailable, explicit source labeling for each identifier, an explicit `unresolved` list rather than omission, and internal cascading through multiple lookup endpoints. These details add significant context that annotations alone do not provide.

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

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

The description is long but every section earns its place: examples, use-case guidance, supported types, and behavioral caveats. It is front-loaded with examples and actionable instructions. It is slightly dense and could be better structured with bullets, but it contains minimal redundancy and is appropriately sized for the tool's complexity.

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

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

Given there is no output schema, the description thoroughly explains what the agent will get back: canonical identifiers per type (CIK, ticker, LEI, FIGI for company; RxCUI, ingredient, brand for drug), source labeling, unresolved list, and graceful failure behavior. It also covers accepted inputs and the internal cascade, making it complete enough for confident 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 description coverage is 100%: it already documents the `type` enum and the `value` formats with examples (ticker, CIK, brand/generic name). The description repeats this and adds context about identifier sources, but it does not materially extend the parameter-level semantics beyond what the schema already states. A baseline of 3 is appropriate.

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

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

The description opens with concrete example queries and then states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It specifies the verb, resource, and output type, and distinguishes itself from siblings by positioning it as the tool to use when a name needs an ID. The supported types (company, drug) and identifier details make 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?

It explicitly instructs 'Use FIRST whenever you have a name but need an ID,' which clearly indicates the primary use case. It also gives example query forms and notes that it replaces 2-3 manual lookups. It does not explicitly state when not to use this tool or name alternatives, but the guidance is strong enough for an agent to select it over siblings like entity_profile.

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/non-destructive. Description adds process details: 'Probes each entity... with ai_visibility_check, ranks by score, surfaces most/least recognized' and specifies return fields (score, confidence, signal density). This is meaningful behavioral info beyond annotations, with no contradiction.

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

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

The description is two sentences, front-loaded with the core action in the first sentence. It packs process, ranking, output fields, and use case without waste.

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

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

Given no output schema, the description compensates by describing returned data ('ranked list with score, confidence, signal density per entity'). It also states the workflow and use case. With good schema coverage, the description is complete for understanding the tool's role.

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

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

Input schema covers all 4 parameters with descriptions at 100% coverage. The description does not add significant parameter details beyond a paraphrase of the entity-first-entry rule already in the schema, 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 'Compare AI visibility across multiple entities side-by-side,' with a specific verb and resource. It also distinguishes from sibling tools by referencing multi-entity comparison and the ai_visibility_check probe, differentiating from single-entity checks.

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

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

Provides explicit use case: 'Useful for competitive AI-marketing audits' with an example question. It implies this tool for comparing multiple entities, but does not explicitly name alternatives or when-not-to-use, so clear context but no exclusions.

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

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

Beyond the readOnly/idempotent hints, the description discloses important dynamic behaviors: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed will list timeouts while the rest still returns. This gives the agent realistic expectations about latency and failure modes.

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 leads with the core purpose, then usage context, then an ecosystem exclusion, and closes with failure behavior in a compact sequence. No word is wasted, and each clause contributes to an agent's ability to use the tool correctly.

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 composite nature (two external services) and no output schema, the description carries the full burden of explaining returns and edge cases. It lists the exact summary fields, per-advisory detail, links, recent versions, and failure behavior, making it complete for a complex tool.

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

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

Schema coverage is 100% (both `package` and `version` are documented in the input schema). The description adds a small extra detail—'Scoped packages (e.g. "@types/node") are accepted'—but otherwise reiterates what the schema already states. Baseline 3 applies because the schema fully covers parameter meaning.

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

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

The description opens with a clear, specific statement: 'Composite "should I add this npm package to my project" check in ONE call' and then enumerates the exact data sources and metrics. It distinguishes itself from sibling tools by focusing on npm dependency evaluation, unlike scan_competitor_ai_presence or validate_claim.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'—directly telling the agent when to invoke it. It also provides an alternative path for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), covering both when and when-not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds substantial behavioral context beyond these: it explains the internal mechanics ('BGE-base-en embeddings + cosine over 500-char overlapping windows'), discloses the 200K character cap with truncation behavior ('longer inputs are truncated and flagged'), and notes that passages carry character offsets for verbatim quote verification. This provides significant transparency not available in structured 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 well-structured and front-loaded, opening with the core action in the first sentence. Every sentence earns its place: usage guidance, technical details, pairing suggestion, and behavioral caveat are all relevant. It is information-dense without redundancy, using about 90 words to convey a large amount of practical information.

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

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

Despite having no output schema, the description explains the return value ('top-N passages with character offsets and similarity scores'). It also covers input semantics, operational limits, and the tool's relationship to other workflows. Given the moderate complexity and the richness provided, the description is complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds practical meaning by framing the 'text' parameter as content 'you already pulled' (e.g., SEC 10-K body, article) and clarifying the 'query' parameter with natural-language examples ('supply-chain risk', 'fiscal year 2024 revenue'). This goes beyond the schema's generic descriptions, earning a 4.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Semantic search INSIDE a fetched record.' It distinguishes from siblings by describing the input-output flow (text + query → passages) and explicitly mentions pairing with ask_pipeworx_grounded, thereby differentiating it from tools that fetch or ground over full documents.

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 the record is too big to cram into the prompt.' It also names an alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This clearly states the tool's role relative to siblings.

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

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

The description goes well beyond the annotations by disclosing behavioral details: returns a subscription id, requires authentication, feed is always on, optional email/SMS with a 10/day cap, webhook signing secret returned once, and auto-disabling after 10 consecutive failures. This provides crucial operational context not available in the annotations alone.

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

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

The description is dense with useful specifics, but it is somewhat long and flows as a single paragraph. It is well-structured sequentially (purpose, auth, types, delivery), and each clause carries meaningful information, though it could benefit from clearer separation of sections.

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

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

Despite no output schema, the description covers the return value (new subscription id), authentication requirements, all subscription types with parameter shapes, delivery options, and operational constraints (verification, limits, webhook auto-disable). This is complete for an agent to select and invoke the tool correctly.

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

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

The schema already covers all parameters at 100%, so baseline is 3. The description adds semantic value with concrete examples for each subscription type (e.g., items:['5.02'] for sec_8k, topic:'fed' for polymarket_edge) and explains delivery channel semantics (phone verification, 10/day cap), which enriches understanding 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 'Create a proactive monitoring subscription to a live-data event stream', which clearly identifies the action (create), the resource (subscription to event stream), and the purpose (proactive monitoring). It also distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation and specifying the returned subscription id.

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

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

The description provides rich context on when to use the tool, including supported subscription types (sec_8k, polymarket_edge, fred_series) with concrete examples, and delivery channels. It states requirements (OAuth account, verified phone for SMS) but does not explicitly name alternatives or exclusion criteria, though the sibling tool list implicitly covers related operations.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful context beyond those: it states the response comes from the live catalog of thousands of tools, includes exact tool+argument shapes, and supports topic filtering. 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 longer than minimal but well-structured: it opens with a list of natural-language queries, then states the purpose, return content, and calling conventions. Every sentence adds value, and the front-loading is effective. Slight redundancy with the schema's topic list prevents a 5.

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?

Since there is no output schema, the description carries the burden of explaining return values; it does so by describing 'category-bucketed example questions' with tool+argument shapes. It also covers usage modes and the live catalog aspect. It doesn't discuss edge cases or errors, but for an onboarding tool this 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%, and the schema already lists all allowed topic values and explains omission behavior. The description's mention of examples like 'finance' and 'pharma' and 'to focus' adds no substantive meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as the onboarding entry point for a newly connected agent, explicitly stating it returns category-bucketed example questions with the exact tool and argument shape. It distinguishes itself from sibling tools like discover_tools by focusing on 'what to ask' and how to call meta-tools.

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

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

The description gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also explains the two calling modes (no args for full spread, or pass topic to focus). However, it does not explicitly mention when-not-to-use or name alternative tools, so it stops short of a 5.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds the soft-delete behavior (row deactivated, not deleted) and the ownership enforcement. This is valuable context that explains the actual effect and what remains accessible afterward.

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

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

Three short sentences: the first states the action, the second adds a critical constraint, and the third explains the soft-delete behavior. No redundant words, and the most important information is front-loaded.

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

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

For a one-parameter cancel tool with strong annotations, the description covers the key behavioral aspects: what it does, ownership limits, and the non-destructive nature. It doesn't mention return values or error cases, but given the simplicity and absence of an output schema, this is sufficient.

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

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

The schema already provides a complete description of the 'id' parameter, stating it's a uuid returned by subscribe, at 100% coverage. The tool description merely says 'by id' without adding additional meaning, 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 opens with 'Cancel a subscription by id,' which is a specific verb+resource+method that clearly identifies the action. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation, and the title reinforces this.

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 clearly states ownership enforcement ('you can only cancel your own subscriptions'), which is a key constraint. The note about deactivation and historical events being available via recent_alerts indirectly suggests when to use this instead of a permanent delete, though it doesn't explicitly name alternatives.

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

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

Beyond the readOnly/idempotent annotations, the description discloses crucial behavioral traits: the six possible verdicts, the meaning of could_not_verify (a failure that is NOT evidence), and unsupported. It also warns callers not to present could_not_verify as evidence and notes that the tool collapses 4–6 sequential calls into one, providing rich, non-obvious 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 long but tightly woven: opening phrase examples, use case, routing logic, return values, error semantics, and a performance note—all essential. It is front-loaded with natural-language triggers and uses semicolons for structured flow, with no filler or repetition.

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

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

For a high-complexity tool with no output schema, the description thoroughly covers the return contract (verdict enum, actual value, citation, reasoning) and special cases (could_not_verify, unsupported). Combined with full parameter schema and safety annotations, the description leaves no critical gap for an agent to invoke it correctly.

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

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

Both claim and tolerance_pct have full schema descriptions (100% coverage), so the schema already explains the parameters. The description adds extra examples for claim and practical guidance for tolerance_pct (e.g., 'set 1–2 for hallucination detection'), which goes beyond the schema's baseline and enriches parameter understanding.

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 specific verbs like 'verify', 'fact check', 'confirm or refute' and names the resource as 'natural-language claim verification against authoritative sources'. It clearly distinguishes from sibling tools by focusing solely on claim verification and explicitly stating it replaces multi-step lookups, leaving no ambiguity about what the tool does.

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

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

The description provides clear usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the routing for company-financial vs. other claims. However, it does not explicitly name sibling alternatives or state when NOT to use this tool, 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.