Arcgis Fairfield

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

Annotations already mark this as read-only and idempotent, lowering the bar. The description adds valuable behavioral details: the default model is free Workers AI Llama-3.3-70b, passing `_apiKey` enables Anthropic probing with a BYO key (and direct payment), and the return shape includes per-model {score, confidence, signals, raw_response} plus a combined view. This goes beyond what annotations provide, though it does not cover rate limits or 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 three sentences, front-loaded with the core action and output, then defaults, then return format, then use cases. Every sentence earns its place with no fluff or repetition of schema details, making it highly efficient and well-structured.

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

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

Despite lacking an output schema, the description compensates by explicitly listing the return structure (per-model fields + combined view). It also covers when to use the tool and the key configuration nuance. It is reasonably complete for a probe tool, though it does not detail the meaning of 'signals' or handle edge cases like invalid keys.

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 enriches parameter understanding by explaining default behavior (omit models for free workers-ai), the conditionality of `_apiKey` (required only if 'anthropic' is in models, passed through to Anthropic), and the cost implication of using the key. This adds meaning beyond the schema field descriptions.

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

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

The description starts with a specific verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It clearly distinguishes from siblings like ask_pipeworx (asking questions) and scan_competitor_ai_presence (competitor-specific), 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 with 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring,' but it does not explicitly mention when not to use this tool or point to alternatives among the siblings. It gives clear usage scenarios without exclusions, so it earns a 4 rather than a 5.

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

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

The description adds meaningful behavioral context beyond the rich annotations (readOnly, openWorld, idempotent, non-destructive): it routes to 5,529 tools, fills arguments, and returns stable pipeworx:// citation URIs. It also notes it works on every tier and is fast. No contradictions with annotations; it could still mention rate limits or error behavior, but the safety profile is already well-covered.

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 ideal but is well-structured and front-loaded with the key instruction ('PREFER OVER WEB SEARCH'). It uses lists, examples, and clear escalation paths. Every sentence serves a purpose, though some redundancy exists (e.g., multiple trigger phrases and examples could be trimmed). Overall, it's organized and scannable.

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

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

For a complex routing tool with no output schema, the description is remarkably complete: it explains what the tool does, the types of questions it handles, how it works under the hood, what the output includes (structured answer with citation URIs), and when to use alternatives. It even addresses edge cases like breaking news and free-tier access.

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 covers the 'question' parameter and its aliases (100% coverage), so the baseline is 3. The description adds value with multiple concrete example questions (e.g., 'current US unemployment rate', 'Apple's latest 10-K') and clarifies that the question can be in natural language, which helps the agent formulate valid queries. It doesn't add syntax details, but the examples and context enrich the semantics.

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

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

The description clearly states the tool's role as a question-answering router that handles factual queries about real-world data, listing concrete domains (SEC filings, FDA, FRED, etc.) and returning structured answers with citation URIs. It explicitly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, making its unique purpose unmistakable.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', with specific trigger phrases like 'what is', 'look up', 'find'. It also gives clear escalation paths to alternatives when needed, naming ask_pipeworx_grounded and deep_research with conditions for stepping up, plus a note on breaking-news use.

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 hints. The description adds valuable context beyond this: the experimental nature, that candidates are only active during tests, that it currently matches the stable version, and that it is a fully functional router rather than a fallback stub. This enriches the agent's understanding of potential behavioral variability.

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, front-loading the core identity ('Beta version of ask_pipeworx') and then logically covering current status, usage, and clarification. Each sentence contributes meaningful information, though it is slightly longer than strictly necessary.

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 beta router with solid annotations and a fully documented schema, the description covers key contextual aspects: identity, experimental nature, current behavior, and usage guidance. The absence of an output schema is mitigated by noting 'same response shape' as ask_pipeworx, which implies expected return format without needing further detail.

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

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

The input schema already provides 100% coverage with clear descriptions for all parameters (question and aliases). The description mentions 'same arguments' but adds no specific parameter details beyond what the schema offers, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with 5,529 tools, and distinguishes it from the stable sibling ask_pipeworx by highlighting its experimental routing improvements. The action ('ask') and resource ('Pipeworx') are explicit, making the purpose unmistakable.

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

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

It explicitly states to use this tool 'exactly like ask_pipeworx when you want the newest routing,' providing a clear when-to-use scenario. It also clarifies the current state (matches ask_pipeworx) but doesn't explicitly mention alternatives like ask_pipeworx_grounded or exclusion cases, so it stops short of full guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds significant behavioral context: the extraction is restricted to tool result content only, the refusal mechanism with detailed refusal_reason enums, the one-extra-LLM-call cost, and the exact output fields including 'evidence (verbatim quote)'. 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 clause earns its place: purpose, routing behavior, grounding mechanism, return shape, refusal reasons, usage context, cost tradeoff, and sibling guidance. It is front-loaded with the most important phrase and then systematically expands. No filler sentences.

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

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

With no output schema, the description fully specifies the return object ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and enumerates all refusal reasons. It also covers operational context (cost, performance vs. sibling). For a complex tool with internal routing, this description is remarkably complete.

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

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

The input schema has 100% coverage with descriptions for the 'question' parameter and all its aliases (q, text, input, query, prompt). The description adds no parameter-specific semantics beyond implying natural language input. Baseline 3 is appropriate when schema fully documents the parameters and description doesn't need to compensate.

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

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

The description opens with a clear, specific verb phrase ('Hallucination-resistant answer mode for high-stakes reads') and explicitly contrasts with ask_pipeworx ('Same routing as ask_pipeworx... then EXTRACTS the answer using ONLY what the tool result contains'). It identifies the resource (Pipeworx) and the exact behavioral differentiator, making it trivially distinguishable from sibling tools.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on... (financial verdicts, legal claims, medical lookups, public statements)' and even gives an when-not-to-use alternative: 'prefer ask_pipeworx for casual lookups' with a concrete cost rationale. This is exactly the exclusionary guidance needed.

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, open-world, and idempotent behavior, but the description adds extensive behavioral detail beyond that. It discloses the resolver contract (market_match_confidence, alternatives, suggestions), warns to 'ALWAYS inspect these before trusting the analysis block,' explains blocking statuses for low-confidence or closed markets, and describes the cancellation-rule risk with EV implications. This goes far beyond the annotations and is genuinely useful for safe invocation.

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 very long, but it is also exceptionally well-structured with clear section headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) and every section contributes distinct operational knowledge. While not concise, it earns its length given the tool's complexity and the absence of an output schema. A small amount of redundancy exists, but the organization mitigates verbosity.

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

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

With no output schema and a complex tool, the description carries the full burden of explaining return values, safety behavior, edge cases, and decision rules. It thoroughly covers response shapes, resolver confidence, parent-event extraction, news fallback behavior, low-confidence suppression, wide-spread illiquidity, and cancellation-rule risks. This is a complete and self-sufficient description for an agent to invoke the tool correctly.

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

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

The input schema covers all three parameters with full descriptions (100% coverage), including the market parameter formats and defaults for depth and include_raw. The description adds behavioral context about fan-out and resolution but does not meaningfully extend the parameter-level semantics; it repeats the market input formats and does not mention depth or include_raw. Since the schema already does the heavy lifting, the baseline of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly differentiates from sibling tools by focusing on Polymarket bet analysis and specifies use cases like 'should I bet on X' and 'is there edge in Z.' The scope and examples make the tool's purpose unmistakable.

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

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

Explicit guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives fan-out examples that show which data sources are relevant for different bet types. However, it does not explicitly name alternative sibling tools or state when NOT to use this tool, so it stops short of a full when/when-not/alternatives treatment.

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

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

The description discloses that it pulls LATEST 10-K financials, handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. This goes beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) to explain data sources and output behavior, without contradicting any annotation.

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

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

The description is densely informative but somewhat long, starting with trigger phrases and then the core functionality. Each sentence adds value, but the trigger list and value-proposition statement make it slightly less concise than ideal. Overall it's well-structured and front-loaded.

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

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

Despite having no output schema, the description covers the tool's inputs, data sources, sorting behavior, and output format (paired data + citation URIs). It also mentions the off-calendar fiscal year handling, making it a complete description for an AI agent to use 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 description adds significant meaning to the 'type' and 'values' parameters beyond the schema. For type='company', it specifies exactly which financial metrics are pulled; for type='drug', it lists adverse-event counts, FDA approvals, and trial counts. It also implies values semantics (tickers/CIKs for company, names for drug) with examples, enriching the schema's brief descriptions.

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

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

The description clearly states it performs side-by-side comparison of 2–5 companies or drugs in a single parallel call, using specific verbs and resources (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs). It distinguishes from sibling tools like entity_profile by focusing on comparisons and explicitly positions itself as preferable to sequential lookups.

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

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

The description provides explicit trigger phrases ('X vs Y', 'which is bigger', 'rank these companies') and states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also outlines the number of entities (2–5) and the distinction between company and drug types, which guides when to invoke.

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

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

The description discloses many behavioral traits beyond annotations: account requirements, paid tier for thorough, gap handling (never invents), contradictions[], semantic excerpting, latency expectations, and citation fetchability. It aligns with the readOnlyHint and does not contradict annotations.

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

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

The description is lengthy but information-dense; every clause adds unique value. However, the core purpose is not front-loaded—the first two sentences are about account requirements and alternatives—so the structure could be improved by stating what the tool does earlier. Still, the text is well-organized and 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?

This is a high-complexity tool with no output schema, yet the description fully compensates: it explains the findings packet structure (verbatim evidence, confidence, source, fetched_at, citations), gaps[], contradictions[], the hop field, and expected latencies. It covers prerequisites, limitations, and edge cases sufficiently for an agent to decide and invoke correctly.

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

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

Although schema description coverage is 100%, the description adds rich meaning beyond the schema: it explains what each depth level does (quick=3 facets, standard=5 with gap recovery, thorough=8 paid with iterative hops) and clarifies that broad and multi-part questions are supported. This goes well beyond the raw parameter descriptions.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explains how it decomposes questions and routes to 5,529 tools. It explicitly distinguishes from siblings, noting it is NOT open-web search and pointing to ask_pipeworx for single lookups and current news.

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: 'Best for broad/multi-part questions over structured data' with examples, and redirects to ask_pipeworx for single lookups and breaking news. It also warns that unsigned users should use ask_pipeworx, giving clear alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context beyond annotations: it returns top-N relevant tools, includes full input schemas with curated examples, and states that results are ready to call directly with no second schema lookup needed.

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

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

The description is three sentences with clear separation: what the tool does, the domain scope, and what it returns/usage advice. The long list of domains is scannable and informative for a discovery tool. No filler or redundancy, though the domain list could be slightly condensed.

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 meta-purpose and the large sibling set, the description adequately covers what it does, when to use it, and what it returns (tool names, descriptions, schemas, examples). It does not explain edge cases like zero results, but that is not critical for a discovery tool without an output schema.

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

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

Schema description coverage is 100%, with every parameter and alias documented. The description adds little beyond the schema—'top-N' implies the limit parameter, and 'natural language description' repeats what the schema says. Thus the baseline of 3 is appropriate because the schema carries the semantic load.

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

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

The description opens with 'Find tools by describing the data or task,' which clearly identifies the verb (find) and resource (tools). It further distinguishes itself from the many sibling tools by explaining that it is the discovery/meta tool, listing specific domains (SEC filings, FDA drugs, FRED data, etc.) that it can search across.

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

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

The description states 'Use when you need to browse, search, look up, or discover what tools exist' and explicitly advises 'Call this FIRST when you have many tools available.' This gives clear when-to-use guidance, though it does not name specific alternative tools or provide explicit when-not-to-use conditions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond these by revealing the parallel fan-out across SEC EDGAR, XBRL, USPTO, GDELT→GNews, and GLEIF, the exact return fields, the patents API sunset soft-fail, and the fallback behavior. 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 and front-loaded, starting with user-intent examples and the key 'ALWAYS PREFER' guidance. It is longer than most, but every sentence earns its place by specifying return fields, limitations, and fallbacks; the length is 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?

There is no output schema, yet the description enumerates all returned fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and describes failure modes like the patents API soft-fail. Combined with rich annotations and full parameter schema, this is complete enough for an AI 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%, so baseline is 3. The description adds concrete examples ('AAPL' or '0000320193'), clarifies CIK padding, and reinforces the name restriction, going beyond the schema's minimal parameter documentation.

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

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

The description uses a specific verb ('profile') and resource ('US public company'), with concrete example phrasings like 'Tell me about X' and 'research Acme'. It clearly distinguishes itself from siblings by stating it is the preferred tool over chaining single-pack SEC/XBRL/news lookups for holistic company 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?

It explicitly states when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. It also provides an exclusion and alternative: names are not supported, and 'use resolve_entity first if you only have a name', naming the alternative tool directly.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds that it deletes a memory and mentions clearing sensitive data, but does not disclose additional behaviors like irreversibility or error handling.

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

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

Two concise sentences, front-loaded with the action, no superfluous text.

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

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

For a simple single-parameter tool with strong annotations, the description covers purpose, usage, and related tools. It doesn't describe return values, but delete operations typically have no meaningful output.

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

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

Schema covers the only parameter key with a description 'Memory key to delete', so 100% coverage. The description mentions 'by key' but adds no additional formatting or semantics beyond the schema.

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

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

The description clearly states the action 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from sibling tools like remember and recall by focusing on deletion.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also points to related tools remember and recall, providing alternative context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds valuable behavioral detail: fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format, as well as noting the output is a single text blob ready for site-root placement.

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

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

Two sentences plus a 'Useful for' list deliver all essential information with no wasted words. It is front-loaded with the core action, then details on process and output, followed by use cases.

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 makes an HTTP request, parses content, and produces a standard file format. The description covers inputs, process, output format, and use cases. No output schema exists, but the response shape is described clearly ('single text blob'). Given the moderate complexity and strong annotations, the description is sufficiently complete.

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

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

Both parameters are fully described in the schema (100% coverage), so the baseline is 3. The description only reinforces the 'url' purpose and mentions link entries, but does not add meaning beyond the schema's existing descriptions.

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

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

The description opens with a specific verb ('Generate') and a precise resource ('production-ready llms.txt file for any URL'), immediately distinguishing this tool from siblings. It also names the target AI crawlers, making the purpose unmistakable.

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

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

It explicitly lists three concrete use cases (client sites, own project, competitor audit), which gives the agent clear context for when to invoke the tool. It doesn't mention when not to use it, but the use-case list is specific enough to infer appropriateness.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful context by specifying what the caller receives (fields, geometry type, record count, capabilities), which goes beyond the annotations without contradicting them. No additional behavioral traits (e.g., rate limits) are disclosed, but they are not expected for a simple read-only schema tool.

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 immediately states the verb and resource, then lists the specific schema components. There is no redundant or filler content, making it highly concise and well-structured.

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

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

With one documented parameter, no output schema, and clear annotations, the description fully covers what the tool does and what it returns. It completely explains the tool's purpose and output given the simplicity of 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?

The input schema covers the only parameter (url) with a clear description and example, achieving 100% coverage. The tool description does not add meaning beyond the schema for the parameter itself; it focuses on the output. 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 states a clear, specific verb ('Get') and resource ('ArcGIS Feature/Map Service layer's schema'), and enumerates the returned components (fields, geometry type, record count, capabilities). This clearly distinguishes it from sibling tools like query_layer, which likely fetch data rather than schema.

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 purpose statement implicitly defines when to use this tool: whenever you need layer schema, not data. While it doesn't explicitly name alternatives or exclusions, the context is unambiguous given the description and sibling tool names. It lacks an explicit 'use when' or 'use instead' statement, so it doesn't earn a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral details: it returns specific fields, filters to the caller's subscriptions, and defaults to active only. This goes beyond the annotations.

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

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

Two sentences: first states purpose and return fields, second gives usage guidance. No wasted words, front-loaded with the core action, and every clause 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?

The tool is simple (one optional parameter), annotations are rich, and the description lists all return fields (id, type, params, created_at, last_fired_at, fire_count) with no output schema provided. It fully equips an agent to invoke the tool correctly.

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

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

Schema coverage is 100% for the single parameter (include_inactive). The description adds no additional meaning beyond the schema—it only repeats the 'active' filtering, which is already implied by the parameter description. Baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'List the caller's active subscriptions.' It clearly states what the tool does and what it returns, distinguishing it from sibling tools like subscribe and unsubscribe by framing it as a review/cancel action.

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

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

The description provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool, though it doesn't name alternatives explicitly, so it falls short of the full 5.

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

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

Even though annotations are all false, the description thoroughly discloses behavior: the claim_token workflow, rate limiting ('Rate-limited to 5 per identifier per day'), the fact that it's free and doesn't count against quota, and the team's daily digest process. It adds substantial context beyond the annotations without contradicting them.

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

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

The description is longer than average (~150 words) but each sentence earns its place: purpose, usage, exclusions, token mechanics, rate limits, and free status. It is well-structured and front-loaded with the most important information, though slightly 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?

Given 4 params, no output schema, and a side-effectful tool, the description covers the key aspects: what triggers use, what to include (tool/pack context), what the response yields (claim_token), and how to follow up. It could mention immediate response status for direct submissions, but overall it is sufficiently complete for an agent to use confidently.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the claim_token parameter's purpose and usage pattern in detail ('pass it back later... to read whether it was fixed'), and by reinforcing the enum semantics (bug, feature, data_gap, praise). This exceeds baseline.

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

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

The description opens with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes this tool from all siblings by focusing on feedback/reporting rather than research or queries, leaving no ambiguity about its 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?

Provides explicit when-to-use scenarios: '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).' Also gives a clear exclusion for tools from other MCP servers and explains how to identify Pipeworx tools, making alternative paths explicit.

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 mark it as read-only and idempotent, and the description adds important behavioral context: it's derived from CF analytics-engine, contains no PII, and is cached for 5min-1h. This goes beyond the schema and helps set expectations about data freshness and aggregation.

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

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

The description is compact but informative, leading with the core function and supplementing with a concise bullet list of use cases. No irrelevant details are present.

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, the description covers purpose, output, caveats about caching and PII, and usage guidance. The lack of an output schema is compensated by the explicit listing of return contents.

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

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

The only parameter 'window' has a rich schema description including enum and semantics for choosing windows. The tool description repeats the window options but doesn't add new meaning beyond the schema, so it meets the baseline for high schema coverage.

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

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

The description clearly states it returns trending data from Pipeworx, specifying output as top tools, top packs, and total call volume. This distinguishes it from sibling tools like discover_tools which focuses on discovery. The verb 'Returns' is specific and accurate.

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 use cases, covering when to use the tool for discovering hot data sources, validating canonical choices, and aligning with agent needs. It lacks explicit exclusions or alternative tool references, but gives clear context for adoption.

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 reveals extensive behavioral details beyond annotations: default behavior scans top ~200 markets, event mode walks child markets and checks ordering/partition sums, topic mode searches related events with a Jaccard similarity threshold, placeholder slugs are filtered, and fill check prices against live CLOB depth. No contradiction with readOnly/idempotent 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 and well-structured with clear sections (modes, semantic anchor, partition filter, response, fill check). Every sentence carries useful information, but it is quite long and could be slightly tightened without losing value. Still, for a complex multi-mode tool, the length is justified.

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

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

The description covers all essential aspects: input modes, response structure (opportunities[], partition_check), edge cases (skipped_low_similarity, placeholders), and post-processing (fill check with realizable vs theoretical edge). It also references a related tool for custom sizing. Without an output schema, this description sufficiently explains return values and interpretation.

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 descriptions already cover 100%, but the tool description adds substantial meaning: event accepts full URLs, topic examples are given, and the behavioral implications of each parameter are explained (single-event vs cross-event). It clarifies how each parameter changes the scan scope and output structure.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes modes (trending_scan, event, topic) and is clearly differentiated from siblings like polymarket_edges and polymarket_fill_risk by naming the alternative for custom sizing.

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

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

Explicit guidance is provided for when to use each mode: 'Call with NO args for a trending_scan... pass event... or topic...' It also states that custom sizing should use polymarket_fill_risk, and explains that cross-event mode catches patterns single-event misses. This gives clear when-to and when-not-to context.

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

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

Annotations already mark the tool as read-only and idempotent, but the description goes far beyond, explaining internal model families (crypto_price, news_momentum, partition_overround), the 24h-move warning, Fed candidate exclusion with rationale, and the 1-hour KV caching. It also discloses why segments may be empty via diagnostics, which is highly transparent.

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 dense wall of text, including internal alpha values, GDELT ratios, and placeholder filters that are not necessary for selecting or invoking the tool. While it uses headings and is organized, it is excessively verbose and far from concise.

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

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

Given the tool's complexity (9 parameters, no output schema), the description fully covers response top-level segments, per-opportunity fields (edge_pp_net, kelly_fraction, etc.), diagnostic counters, and caveats like the Fed note. It leaves no ambiguity about what the agent will receive or how to interpret edge conditions.

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 critical context by clarifying that min_kelly does not filter partition_overround opportunities because parent-level kelly is 0, and min_partition_leg_kelly applies per-leg. It also labels min_liquidity and max_spread_pp as 'tradeable-edge filters,' which enhances 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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' using a specific verb and resource. It clearly distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on cross-referencing Pipeworx data with Polymarket prices.

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 'Built for "what should I bet on today"' gives a strong contextual signal for when to use it. It also details tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) that help filter for realizable edges, but it does not explicitly name alternative tools or state when not to use this one.

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 details the response structure (tracked[], expired[], snapshot_dates[]), limitations (60-day TTL, snapshot gaps from cache-miss), and calculation methodology (decay from daily closes, absolute value convention). This far exceeds the annotations and provides critical operational context.

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

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

The description is dense but well-organized, starting with the core question, then covering parameters, response fields, and limitations in a logical sequence. Each sentence adds necessary value—there is no fluff or redundancy—making it 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 the absence of an output schema, the description fully specifies the response fields and their semantics, including trend values, decay calculation, expiry reasons, and snapshot date gaps. It also covers history depth and data caveats, making it complete for a complex telemetry 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 input schema already covers both parameters completely (days with default and clamp range, window with allowed values). The description restates the defaults and adds 'snapshot family' terminology but does not provide any additional meaning beyond the schema. With 100% schema coverage, the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a specific question about edge age and shrinkage. This distinguishes it from sibling tools like polymarket_edges by focusing on historical time-series rather than current edge values.

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

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

The description provides clear context for when to use the tool ('Answers how long has this edge existed and is it shrinking?') and uses an example to illustrate trade relevance. However, it does not explicitly name alternative tools or state when not to use it, falling 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 mark it readOnly and non-destructive; the description adds critical behavioral disclosure beyond that: it walks the order-book ladder, can partially fill (shares_filled, max_fillable_usd), and exposes risk flags like thin_legs and forced_directional_risk. It honestly warns about the dominant loss mode in arb-bot P&L, which is exactly the kind of context annotations cannot convey. 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 lengthy but tightly organized: summary line, REQUIRES clause, SINGLE-MARKET block, BASKET block, and a bolded USE THIS directive. Every sentence carries either a configuration detail, a return value, or a risk warning. The caps-lock emphasis and block structure make it skimmable despite its density.

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 two modes, four parameters, and absence of an output schema, the description is remarkably complete. It enumerates output fields for both modes, explains the economic rationale, gives defaults and clamps, and includes failure/risk semantics. Without an output schema, this description shoulders the burden exceptionally well.

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?

Though schema coverage is 100%, the description goes much deeper: it clarifies the market vs event mode dichotomy, gives side values per mode with defaults, explains size_usd interpretation (max spend vs target proceeds vs settlement notional), and notes the clamp range. It also reveals an important constraint invisible in the schema (required: one of market or event). This substantially 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 opens with a precise verb-resource pair: "Realizable-vs-theoretical edge check against live CLOB order-book depth." It clearly differentiates from sibling tools by explicitly naming polymarket_arbitrage and polymarket_edges and positioning itself as the pre-trade fill-risk validator for those signals.

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

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

It states exactly when to use: "USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500." It also explains the consequence of not using it (partial fills → unhedged directional position) and gives mode-level instructions (REQUIRES one of market/event).

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

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

The description discloses much more than the annotations: it explains when compatibility_warning fires (two specific cases), what temporal_alignment indicates, and how skipped_cross_type/subtype counters work. This gives the agent a detailed model of edge cases and failure modes. No contradiction with the readOnlyHint/annotations exists.

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

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

The description is long but well-organized with clear section markers (TWO MODES, RESPONSE, SAFETY FIELDS) and each sentence contributes operational or safety information. It is front-loaded with the core purpose and then dives into details, making it appropriately sized for a complex cross-venue comparison tool.

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

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

With no output schema, the description carries the full burden of explaining return values (leg-by-leg prices, matched spread[].top_spreads_pp) and edge cases (compatibility_warning, temporal_alignment, skipped_cross_type). It is thorough enough for an agent to invoke the tool and interpret results correctly.

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

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

Although the schema already covers all three parameters, the description adds significant semantics: it explains the two modes, how topic shortcuts auto-fetch events, how explicit overrides interact with topic, and what the response will contain. This goes well beyond the schema's per-parameter descriptions.

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

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

The description clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, which is a specific verb+resource+scope. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on Kalshi–Polymarket pairings and explicitly describing the two modes of operation.

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

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

The description provides clear usage guidance with TWO MODES: using pre-mapped topic shortcuts versus explicit custom pairings. It also warns that pre-mapped topics often return compatibility_warning and that pre-mapped ≠ tradeable, which helps an agent decide when to rely on the tool. It doesn't explicitly name alternative tools, but the mode guidance is substantial.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by noting that the query returns attribute rows and geometry, and by clarifying the SQL-like parameter semantics. No contradiction with annotations.

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

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

The description is three sentences with no wasted words. It front-loads the purpose, then lists parameters in a compact format, and ends with a useful example tip. Every sentence contributes meaningful information.

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

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

Given 6 parameters and no output schema, the description covers the essential aspects: what it does, the input pattern (URL from search_datasets), key parameter usage, and return type (attribute rows and geometry). It doesn't detail error handling or pagination beyond schema, but for a query tool with complete schema documentation, this is adequate. A slightly more explicit mention of pagination behavior would have made it a 5.

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 6 parameters, so the baseline is 3. The description adds value by grouping parameters (SQL-like where, comma-separated out_fields, etc.) and clarifying that output includes geometry, which is not explicitly stated in the schema. This enhancement pushes the score above baseline.

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

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

The description clearly states the tool queries an ArcGIS Feature Service / Map Service layer by URL, distinguishing it from siblings like layer_info (which presumably describes layer metadata) and search_datasets (which finds datasets). The verb 'Query' is specific and the resource is well-defined.

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

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

The description provides clear context by stating the URL comes from search_datasets, and it includes a practical sampling tip (where="1=1" + out_fields="*"). However, it does not explicitly mention when not to use this tool or name alternative tools for related tasks, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context beyond annotations: the scope to an identifier (anonymous IP, BYO key hash, or account ID) and the dual-mode behavior (retrieve vs. list all when key omitted). This goes beyond what annotations 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?

Three sentences, each earning its place: the first defines the action, the second provides a concrete use case, and the third clarifies scope. No redundancy or filler; front-loaded with the primary purpose.

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

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

For a simple retrieval tool with one optional parameter, the description covers the core behavior, use context, scope, and related tools. It does not specify the return format (e.g., error behavior for missing keys), but the lack of an output schema makes that less critical. Overall, it is sufficiently 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 input schema fully describes the 'key' parameter with clear semantics ('omit to list all keys'). The description essentially repeats this behavior and adds only illustrative examples (ticker, address, notes) rather than new parameter meaning. With 100% schema coverage, the baseline of 3 is appropriate; the description does not significantly 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 clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses specific verbs and identifies the resource (memory keys), and distinguishes itself from sibling tools by explicitly mentioning remember and forget.

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

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

It provides explicit guidance on when to use the tool: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also names the paired tools (remember, forget) for complementary actions, offering clear alternatives.

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

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

The description discloses the mark_read side-effect (flagging events read), which is beyond the readOnly annotation. It also explains the persisted feed and mentions that polling works fine, adding value 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: purpose, filtering/state, and alternative access. It is front-loaded with the main action and contains no redundant information—every sentence earns its place.

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

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

With no output schema, the description adequately describes the return payload (source, citation_uri, raw event payload). It covers filtering, mark_read, polling, and the alternative endpoint, fully explaining the tool's behavior without needing further documentation.

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

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

The schema already provides 100% coverage for all parameters, but the description adds a concrete type example ('sec_8k') and explains how mark_read affects subsequent calls. This goes beyond the schema's descriptions, making parameters more actionable.

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

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

The description opens with 'Pull fired events from your subscription feed,' which is a specific verb+resource. It clearly distinguishes from sibling tools like list_subscriptions by focusing on fired events rather than subscription management, and it specifies the return contents.

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

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

The description gives clear usage context: filtering options, mark_read behavior, and an alternative HTTP endpoint for scripts/dashboards. It doesn't explicitly name an alternative tool within the sibling list, but the guidance is sufficient for deciding when to use this tool.

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

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

The description goes well beyond the annotations by disclosing the underlying data sources (SEC EDGAR, GDELT→GNews fallback, USPTO), the fallback logic (GDELT preferred, GNews when rate-limited or 5xx), and a known limitation (USPTO soft-fails after PatentsView sunset). It also details return structure, which is especially important given no output schema.

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

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

The description is detailed but every sentence contributes: purpose, use cases, sources, fallbacks, parameter details, return format, and alternative. It is front-loaded with the core purpose and structured logically. 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?

Given the tool's complexity (multiple data sources, fallback logic, no output schema), the description covers all essential aspects: what it does, when to use, parameter formats, return structure, and an alternative. It also flags a known degradation (USPTO soft-fail). The description is fully sufficient 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 coverage is 100%, so the baseline is 3. The description adds specific examples for the `since` parameter ("7d", "30d", "3m", "1y") and recommends "30d" or "1m" for typical monitoring, which enriches the schema description. It does not add extra meaning for `type` or `value` beyond the schema, but the added `since` guidance justifies a 4.

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

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

The description begins with concrete query patterns ("What's new with X") and states it is a "change feed for a company in the last N days/weeks/months in ONE parallel call." This clearly identifies the tool's function and scope, and explicitly differentiates from the sibling tool entity_profile by explaining when to use the static profile instead.

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 through example queries, explains the parameter semantics, and includes an explicit alternative: "Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window." This gives clear context for choosing between 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?

Adds behavioral context beyond annotations: memory is scoped by identifier, persistence differs for authenticated users (persistent) vs anonymous (24 hours). Annotations already declare idempotentHint=true, destructiveHint=false, and the description does not contradict them. It does not mention overwrite behavior for duplicate keys, but the idempotency hint partially covers repeated calls. Overall, good transparency for a simple key-value store.

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

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

The description is three well-structured sentences, front-loaded with the primary action. Every sentence adds value: first defines what it does, second gives when to use, third explains scoping/persistence and pairs with related tools. No wasteful 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?

Given the tool's simplicity (2 string parameters, no output schema) and the richness of annotations (idempotent, non-destructive), the description fully covers usage context, persistence behavior, and relationship to sibling tools. There is no gap in information that would prevent correct invocation.

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

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

Input schema has 100% coverage with descriptions for both key and value. The description adds practical examples for the key format ('subject_property', 'target_ticker', 'user_preference') and clarifies the value as 'any text — findings, addresses, preferences, notes.' This enriches the schema but is not strictly necessary given the schema already defines the parameters well.

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: 'Save data the agent will need to reuse later — across this conversation or across sessions.' It names the verb (save), the resource (data), and the scope (across conversations/sessions). It also distinguishes from siblings by mentioning paired tools recall and forget, making the purpose unambiguous.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject).' It also names alternatives for complementary operations: 'Pair with recall to retrieve later, forget to delete.' This clearly instructs the agent on when to invoke this tool and when to use related 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?

Beyond the annotations (read-only, idempotent, open-world), the description discloses internal cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit labeling of unresolved identifiers, and source attribution for each identifier. These are non-obvious behaviors an agent would need to know.

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?

While the description is longer than ideal, it packs substantial information into a structured format. The example phrasings at the start are a bit repetitive, but each section (supported types, degradation, rationale) earns its place for a tool with this complexity.

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

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

The description covers purpose, usage, supported types, return semantics, failure modes, and its role in a multi-step workflow. For a tool with no output schema, it gives a clear picture of what will be returned and how to handle edge 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?

The schema already covers both parameters (type and value), but the description enriches them by specifying what each entity type returns (e.g., CIK+ticker+LEI+FIGI for company, RxCUI+ingredient+brand for drug) and acceptable input formats (ticker, CIK, name; brand/generic). This goes beyond the schema's simple descriptions.

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

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

The description opens with concrete user questions and immediately states the tool's function: resolving user-spoken names to canonical/official identifiers required by other tools. It clearly distinguishes this from sibling tools like entity_profile or compare_entities by focusing on name-to-ID conversion as a prerequisite step.

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 instruction 'Use FIRST whenever you have a name but need an ID' provides an explicit trigger condition for using this tool. It also explains the tool's role relative to other tools ('identifiers other tools require as input') and notes that it replaces multiple manual lookups, though it doesn't explicitly name alternative tools or state 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 and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context by explaining the multi-probe process ('Probes each entity with ai_visibility_check'), ranking behavior, and return format ('ranked list with score, confidence, signal density per entity').

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

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

The description is three sentences with no fluff: it opens with a clear headline, explains the process and use case, and states the output format. Every sentence contributes value.

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

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

Despite having no output schema, the description explicitly lists return fields ('score, confidence, signal density'). Combined with rich annotations and a comprehensive input schema, it gives 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 all parameters having detailed descriptions (e.g., entities being first entry as subject). The tool description adds minimal parameter-level meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It names the exact resource (AI visibility) and distinguishes from siblings by explicitly mentioning it probes each entity with ai_visibility_check and ranks results, which is distinct from the single-entity sibling tool.

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

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

The description provides a clear use case: 'Useful for competitive AI-marketing audits' with a concrete example query. It implies when to use this tool over a single-entity check but does not explicitly name alternatives or 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 annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses critical behavioral traits: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and on timeout sources_failed lists it while other data still returns. This adds real context not available in annotations or schema.

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

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

The description is longer than average but every sentence contributes: purpose, use-case, return payload, ecosystem limitation, and failure behavior. It is front-loaded with the main purpose, and while detailed, it avoids redundancy. Slightly dense but well-structured.

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

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

With no output schema, the description compensates by listing the exact summary fields (is_latest, license, published_at, etc.), per-advisory detail, links, and alternative versions. It also covers error handling and performance caveats, making the tool's behavior fully understandable in context.

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

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

Schema description coverage is 100%, with package and version both well-documented. The description does not add new parameter-level semantics beyond the schema; it contextualizes them within the composite check but the baseline 3 is appropriate because the schema already 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 the tool's purpose with a specific verb: "Composite 'should I add this npm package to my project' check in ONE call". It names the exact resources (deps.dev, bundlephobia) and distinguishes it from sibling tools by emphasizing its unique scope of npm dependency evaluation.

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

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

Explicit usage guidance is provided: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'". It also gives an alternative for non-npm ecosystems (PyPI/Maven/Cargo/Go under deps.dev:version directly), which helps an agent decide when NOT to use this tool.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds value by explaining the return fields (name, summary, record_count, owner/org, Feature Service url) and the linkage to query_layer/layer_info. 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?

Two sentences with a clear front-loaded purpose, followed by return-value details and usage guidance. Every word contributes, and the structure is easy to scan.

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

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

With no output schema, the description compensates by enumerating the return fields and their role in the workflow. It covers the essential behavior for a search tool, though it omits minor details like result ordering or pagination, which are not critical given the simple interface.

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

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

Schema description coverage is 100%, with all parameters (query, limit, org_id) already described in the input schema. The description adds context by listing example data categories ('parcels, zoning, public works & city services') but does not enhance parameter understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Search' and the resource 'City of Fairfield GIS open geospatial datasets' with specific examples (parcels, zoning, public works & city services). It distinguishes itself from sibling tools like query_layer and layer_info by noting that this tool returns dataset metadata and a Feature Service url to pass to those tools.

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

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

Provides clear context for use: 'by keyword' and states that the returned url should be passed to query_layer / layer_info, which highlights how it fits into a workflow. However, it does not explicitly state when not to use this tool versus alternatives, 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?

Despite readOnlyHint and idempotentHint annotations, the description adds substantial behavioral detail: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char overlapping windows, and enforces a 200K char cap with truncation and flagging. This goes well beyond the annotations' safety profile.

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

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

Three sentences that are front-loaded with purpose, then usage, then technical specifics. Every sentence earns its place; no filler 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?

With no output schema, the description explicitly covers the return format (top-N passages with offsets and scores). It also explains input constraints (200K cap), the algorithmic approach, and the complementary sibling tool. For a search tool with this complexity, the description is fully 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 meaning with concrete examples (e.g., 'a SEC 10-K body' for text, 'supply-chain risk' for query) and clarifies the relationship between limit and top-N passages. This elevates it above the baseline but doesn't reach 5 since the schema already captures the core semantics.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' a specific verb+resource that clearly states what the tool does. It distinguishes itself from sibling tools like ask_pipeworx and ask_pipeworx_grounded by emphasizing it operates on already-fetched text, not external knowledge, and pairs with ask_pipeworx_grounded for a two-step workflow.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also gives a workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This provides clear context and an alternative/complement, satisfying the 'when/when-not/alternatives' criterion.

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?

Adds behavioral details beyond annotations: requires OAuth account, phone verification, 10/day SMS cap, always-on feed, and returns a subscription id. These complement the readOnlyHint/idempotentHint annotations without contradiction.

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

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

The description is dense but every sentence contributes meaningful information. It is front-loaded with the core purpose and then structured logically: auth, types, delivery.

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

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

Despite lacking an output schema, the description covers the essential aspects for a creation tool: prerequisites, supported types with examples, delivery options, rate limits, and return value (subscription id). It is comprehensive for the tool's complexity.

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

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

Schema coverage is 100%, and the description adds practical examples and clarifies type-specific parameter usage (e.g., items:['5.02'], topic:'fed', series_id:'UNRATE') beyond the schema descriptions.

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

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

The description opens with a specific verb+resource phrase: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes this from sibling tools like list_subscriptions or unsubscribe by focusing on creation and enumerating supported types.

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

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

Provides clear context including the required OAuth account prerequisite, supported subscription types, and delivery channels. It does not explicitly state when not to use the tool or name alternatives, but the context strongly implies its role.

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 cover read-only, open-world, idempotent, and non-destructive. The description adds significant behavioral context: it pulls from the 'live catalog of thousands of tools', returns category-bucketed examples with exact tool/argument shapes, and explains behavior with or without the `topic` parameter. This goes well beyond the annotations.

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

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

The description is a single dense paragraph that front-loads the key question it answers, then details return format and optional input. It is longer than minimal but every sentence adds value for a discovery tool, so it earns a 4 rather than 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?

With no output schema and low complexity, the description gives complete context: what it returns (category-bucketed examples), how it behaves (live catalog, exact tool+arg shape), and when to use it (first/onboarding). This fully covers the tool's usage 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 description already documents the single optional `topic` parameter with its categories and the omit-for-full-spread behavior. The description rephrases these examples ('finance', 'pharma', 'betting') without adding new syntax or semantics, so the baseline of 3 applies given high schema coverage.

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

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

The description states the tool is 'the onboarding entry point' that returns 'category-bucketed example questions' with 'the exact tool + argument shape' for each. This specific verb+resource framing clearly differentiates it from siblings by positioning it as the first tool to use when unfamiliar with 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?

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. This provides strong when-to-use guidance, but it lacks explicit when-not-to-use or alternative tool recommendations beyond learning, so it's not 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?

The description goes beyond the annotations by disclosing ownership enforcement and the deactivation (soft-delete) behavior, explaining that historical events remain available via recent_alerts. This is consistent with the annotations (destructiveHint: false, idempotentHint: true) and adds valuable side-effect 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 exactly two sentences, front-loaded with the action, and every clause adds meaningful information: the cancel action, ownership constraint, and the deactivation effect. No fluff or redundancy.

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

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

For a simple one-parameter tool with no output schema, the description fully covers what the tool does, its constraints, and the consequence for historical data. It even references recent_alerts to close the loop on data availability, making it self-contained.

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 id parameter (uuid, returned by subscribe) with 100% coverage. The description only repeats 'by id' without adding new semantic meaning, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific action and target: 'Cancel a subscription by id.' It clearly differentiates this tool from siblings like subscribe and list_subscriptions by focusing on the cancellation action, and further clarifies the soft-delete behavior vs. hard deletion.

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

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

The description implies the correct usage context (cancelling a subscription) and adds an important constraint: 'you can only cancel your own subscriptions.' However, it does not explicitly name alternative tools or state when not to use this tool, so it falls just short of full explicit guidance.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description reveals the verdict vocabulary, the critical caveat that could_not_verify indicates the check didn't happen (with verification_error) and must not be used as evidence, the difference between unsupported and could_not_verify, and the two pipeline paths. This is substantial behavioral context.

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

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

The description is front-loaded with trigger phrases and structured logically from purpose to routing to returns to caveats. Every sentence carries useful information, but it is fairly long. It earns a 4 because the density is warranted by the tool's complexity and the important error-handling warning.

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 specifies the input types, the routing logic, the verdict enum, the return payload (value + citation + reasoning), and the meaning of each error state (could_not_verify vs unsupported). It also mentions efficiency gains. No significant gaps remain.

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

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

The input schema already provides 100% coverage with detailed descriptions for both claim and tolerance_pct, including examples and default behavior. The description does not add parameter-specific semantics beyond the schema; it only mentions percent-delta math at a high level. Baseline 3 applies.

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

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

The description opens with trigger phrases ('fact check', 'verify the claim that…') and explicitly states it performs natural-language claim verification against authoritative sources. It distinguishes its coverage between company-financial claims (SEC EDGAR/XBRL path) and all other factual claims (grounded pipeline), and notes it replaces 4–6 sequential calls, clearly differentiating it from sibling research tools.

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

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

It gives an explicit usage condition: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing between financial and non-financial claims. However, it does not name alternative tools or provide when-not-to-use exclusions, so it falls 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.