Arcgis Fontana

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

Annotations already declare readOnly=true, openWorld=true, idempotent=true. The description adds valuable context beyond that: Workers AI is the free default model, passing _apiKey uses Anthropic with direct payment, and it describes the return shape (per-model {score, confidence, signals, raw_response} + combined view). No contradiction with annotations, though it could mention rate limits or failure modes. With strong annotation coverage, this is solid.

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 with no fluff: purpose, default/optional behavior, and return/use cases. Each sentence earns its place, and the most important information is front-loaded.

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

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

For a tool with 4 parameters and no output schema, the description covers the return structure and use cases well. It lacks edge-case handling (e.g., invalid model names) and rate-limit info, but for a read-only probe tool this is sufficiently complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by specifying the default model (workers-ai) and clarifying that _apiKey is only needed for Anthropic probing, including the cost implication. This goes beyond what the schema explicitly states.

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: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It clearly states the output and distinguishes itself from sibling tools like ask_pipeworx (Q&A) and scan_competitor_ai_presence by focusing on multi-model visibility scoring.

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 contexts: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not explicitly mention alternatives or when not to use this tool, 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/openWorldHint/idempotentHint, and the description adds context about routing to 5,564 sources, returning citations, working on every tier, and being a single fast call. It doesn't mention failure modes but annotations cover the safety profile, and the description adds significant behavioral context beyond 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?

Long but front-loaded with the key directive 'PREFER OVER WEB SEARCH'. Each sentence contributes context about usage, alternatives, or examples; no filler. Slightly verbose but justified by the tool's broad scope and the need to guide tool selection.

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

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

Despite no output schema, the description states the return format (structured answer with citation URIs). Covers trigger conditions, examples, escalation paths, and tier compatibility. Adequate for an agent to decide when and how to use it, even for a complex routing tool.

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

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

Schema description coverage is 100% and the 'question' parameter is well-defined; all aliases are described. The description provides numerous example queries (e.g., 'current US unemployment rate', 'Apple's latest 10-K') that enrich understanding but don't add new parameter-level constraints 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?

Description specifies 'Routes the question to the right one of 5,564 tools across 1462 verified sources, returns the structured answer with stable pipeworx:// citation URIs.' Clearly distinguishes from siblings by positioning as default entry point and contrasting with ask_pipeworx_grounded and deep_research.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'; gives trigger phrases ('what is', 'look up', 'get the latest') and names alternatives like ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad questions. Also explains 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 read-only, idempotent, and non-destructive behavior. The description adds valuable context about the live experimental nature, candidate routing improvements being tested, and that it is a fully working router rather than a stub. 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?

Four sentences, each dense with essential information: beta identity, identical toolset, experimental state, usage guidance, and the clarification that it is not a fallback. Front-loaded with purpose and efficiently structured.

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

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

For a beta router with no output schema, the description fully explains the tool's purpose, current runtime state, relationship to the stable router, and usage context. Complete enough for an agent to select and invoke it correctly.

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

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

The schema covers all parameters at 100% (aliases for 'question'). The description adds that the arguments are identical to ask_pipeworx, clarifying that the question parameter serves as the routing query. This reinforces the schema's meaning without repeating 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 identifies the tool as the beta version of the universal router, stating it has the same 5,564 tools and arguments as ask_pipeworx. It explicitly differentiates from the stable sibling by noting the experimental routing improvements, making it distinct from ask_pipeworx and ask_pipeworx_grounded.

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

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

Provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies the current state (no active candidate, so it matches ask_pipeworx exactly). This tells the agent when to choose this beta router over the stable alternative.

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

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

Annotations already mark this as read-only, open-world, idempotent, and non-destructive, so there is no contradiction. Beyond those annotations, the description reveals key behavioral traits: it may return an explicit refusal with a structured refusal_reason enum, it fetches data through tool routing, and it incurs an extra LLM call. This provides substantial actionable context beyond the annotations.

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

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

The description is dense but every clause earns its place: purpose, routing behavior, extraction guarantee, return shape, refusal reasons, use cases, and cost tradeoff. It is front-loaded with the key differentiator ('Hallucination-resistant answer mode for high-stakes reads') and avoids fluff or repetition.

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

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

Despite having no output schema, the description fully compensates by specifying the exact success response shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and the refusal variants. It also gives performance/cost context and clear invocation guidance, making the tool's behavior completely understandable for an agent.

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

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

The schema covers 100% of the parameters and already describes question and all five aliases with clear descriptions. The description adds no additional parameter semantics, but with full schema coverage and a single conceptual parameter, a baseline 3 is appropriate: schema carries the burden and does so adequately.

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-oriented purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes itself from the sibling tool ask_pipeworx by noting it uses 'Same routing' but then 'EXTRACTS the answer using ONLY what the tool result contains,' which differentiates the grounded vs. ungrounded behavior.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete domains like financial verdicts, legal claims, and medical lookups. It also provides an explicit exclusion and alternative: 'prefer ask_pipeworx for casual lookups,' plus a cost-based tradeoff ('Costs one extra LLM call').

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

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

The description goes well beyond the annotations by detailing resolver contracts, status codes ('low_confidence_match', 'market_closed_or_inactive'), safety mechanisms, fan-out behavior, fallback handling (news _fallback_attempted), and resolution-rule risk (cancellation_rule). It even reveals a 'recurring pure-rules loss' from arbitrage, adding critical behavioral context that annotations cannot convey. No contradiction with the readOnly/idempotent hints.

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

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

Despite being long, the description is exceptionally well-structured with clear labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY, etc.). Every sentence carries substantive information about behavior, edge cases, or data sources. The front-loaded purpose and usage lines immediately orient the agent, and the length is justified by the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining return values. It comprehensively covers response shapes (result.market, result.analysis, result.evidence), resolver contract fields, parent_event extraction, news fallback fields, safety statuses, and cancellation rules. Given the complexity of fan-out to multiple data sources, this description is remarkably complete and anticipates the agent's needs.

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 parameters are fully documented in the input schema. The tool description adds some context about accepting slug/URL/question text and the depth/include_raw behavior, but this is largely redundant with schema descriptions and examples. The description doesn't significantly extend parameter understanding beyond what the schema already provides.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It then details the exact inputs (slug, URL, question text) and the process (resolve, classify, fan-out, return evidence packet + comparison). This clearly distinguishes it from siblings like polymarket_edges or validate_claim, which focus on different aspects.

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 given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This states when to use the tool, but it does not explicitly contrast with alternatives like polymarket_edges or validate_claim. However, given the context signals, the guidance is sufficient for an agent to select appropriately.

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

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

Annotations already establish readOnly/idempotent/non-destructive. The description adds crucial behavioral details: data sources (SEC EDGAR/XBRL, FAERS, FDA), specific metrics pulled, handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. 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 dense but every sentence adds value: trigger phrases, data sources, edge-case handling, sorting behavior, and return format. It is front-loaded with examples and uses brief, scannable phrases. No redundant content.

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

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

With no output schema, the description compensates by specifying what is returned (paired data, citation URIs), how results are sorted, and the data sources. For a two-parameter tool, this fully covers the information an agent needs to invoke it correctly and understand the outcome.

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 covers parameter names and types, the description enriches meaning by explaining what each 'type' value actually fetches (10-K financials vs. adverse-event/trial counts) and provides concrete value examples (tickers, drug names). This goes beyond the schema's minimal 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. It lists numerous trigger phrases and explicitly distinguishes from sequential single-entity lookups, making its purpose unmistakable.

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

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

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides concrete examples of queries that should invoke it. This gives clear when-to-use guidance and implicitly contrasts with the sibling entity_profile 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?

Extensive disclosure beyond annotations: describes parallel decomposition, findings packet structure (evidence, confidence, source, fetched_at), gap handling, contradictions, hop field, citation_uri conditions, and the semantic excerpting behavior. Annotations (readOnlyHint, idempotentHint) are consistent, and the description adds rich operational detail without contradiction.

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

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

The description is long but every section contributes value—account context, alternatives, depth details, citation semantics, performance expectations. Slight verbosity (e.g., 'in ONE call', 'this is NOT open-web search') could be trimmed, but overall it is well-structured and information-dense.

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 only two params and no output schema, the description covers return format, error/edge cases (gaps), contradictions, performance, and authorization—far exceeding expectations. It is complete enough for an agent to decide when and how to invoke the tool without external doc.

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

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

Although schema coverage is 100%, the description deepens understanding of both parameters. For 'depth', it explains the facet count and gap-recovery behavior, and the 'question' parameter is given guidance on natural-language breadth. It adds context far beyond the schema enum and property descriptions.

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

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

The description uses a specific verb ('research') and a clear resource ('Pipeworx's 1462 STRUCTURED data sources') and explicitly distinguishes itself from siblings ('this is NOT open-web search', 'For a single lookup use ask_pipeworx'). It makes the tool's purpose and scope 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?

Provides explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and when-not-to-use with named alternatives ('For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). Also covers account requirements and depth-level usage, making it far beyond minimal.

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

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

Annotations already declare the tool safe (read-only, idempotent, non-destructive). The description adds valuable behavioral detail: it returns names, descriptions, and full input schemas with examples, and states results are directly callable without a second lookup. 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 front-loaded with the core purpose and flows logically through usage, return format, and ordering guidance. The domain list is long but directly informative. Each sentence earns its place; only minor redundancy with the schema's alias documentation.

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 meta-tool, the description covers all essential aspects: what it does, when to use it, what it returns, and why it's useful (no second schema lookup). With no output schema, it adequately describes return structure. Could mention pagination or ranking behavior, but not critical for this tool.

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

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

Schema description coverage is 100% with detailed docs for each parameter (query, aliases, limit). The description reinforces the query as a natural-language task description and lists example domains, but this is already implied by the schema's own examples. No significant extra meaning beyond the schema.

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

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

The description leads with 'Find tools by describing the data or task,' which is a specific verb+resource statement. It also lists covered domains (SEC filings, FDA drugs, etc.) and explicitly positions the tool as a discovery/overview mechanism, clearly distinguishing it from the sibling tools that execute specific data tasks.

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

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

The description gives explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implies a when-not-to-use (when you already know the exact tool) but does not name specific alternative tools, so it falls slightly short of the highest bar.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds substantial behavioral context: fans out across SEC EDGAR, XBRL, USPTO, GDELT/GNews, GLEIF; details specific output fields and sorting; explains the patent API sunset soft-failure and GDELT→GNews fallback chain. No contradiction with annotations.

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

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

The description is long but front-loaded with examples to trigger recognition, then moves from purpose to usage guidance to behavior to input constraints. Some redundancy exists (e.g., repeating 'names not supported' which is already in the schema), but every sentence carries meaning and the structure is logical.

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

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

Given the tool's complexity and the absence of an output schema, the description thoroughly enumerates all return categories (CIK, recent_filings with URIs, fundamentals, patents, news, LEI) and includes caveats like the patent API sunset and soft-fail behavior. It leaves no critical gaps for an agent to invoke correctly.

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

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

The input schema already documents both parameters with 100% coverage: type (enum "company") and value (ticker/zero-padded CIK, names not supported). The description repeats this information with the same examples and does not add new semantic detail beyond what the schema provides. Baseline 3 for high schema coverage 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 multiple real-world query examples ("Tell me about X", "research Acme", "brief me on Tesla") before stating the core purpose: 'full cross-source profile of a US public company in ONE parallel call.' This clearly distinguishes it from sibling single-source lookup tools and uses a specific verb+resource pair.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' providing a clear when-to-use directive. It also states what not to pass (names) and directs users to resolve_entity as a prerequisite, giving concrete 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 adds behavioral context beyond annotations: it explains that the tool clears previously saved data and is appropriate for stale or sensitive content. Annotations already declare destructiveHint=true and idempotentHint=true, so the description complements rather than contradicts them, though it could mention idempotent behavior on missing keys.

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

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

Two sentences, front-loaded with the action, followed by usage guidance and sibling relationships. Every word earns its place without unnecessary elaboration.

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

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

For a simple one-parameter deletion tool with robust annotations and a clear schema, the description covers purpose, usage, and context. No output schema exists, so the description needn't explain return values. It is complete for agent decision-making.

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 description ('Memory key to delete') fully covers the single parameter, and the schema provides an example key. The tool description adds no new parameter details, but with 100% schema coverage, the 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 ('Delete'), the resource ('a previously stored memory'), and the mechanism ('by key'). It distinguishes this from sibling tools 'remember' and 'recall' by explicitly positioning it as the deletion counterpart.

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

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

Provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names sibling tools to pair with, clarifying how it fits into the broader memory workflow.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond that by explaining the fetch-extract-emit workflow and the output format ('a single text blob ready to drop at site-root/llms.txt'). This complements 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 four sentences, with the primary purpose front-loaded in the first sentence. Each sentence adds distinct value: purpose and audience, process, output format, and use cases. There is 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?

The tool is simple with only two parameters, strong annotations, and a well-described output. The description covers what it does, how it behaves, and when to use it. Sibling tools are unrelated, so no additional disambiguation is needed. The description is complete for this tool's complexity.

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

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

Schema description coverage is 100% for both parameters (url and max_links), including default/max for max_links. The description does not add significant parameter-specific detail, but it provides context about what the tool does with the URL and the output, which indirectly clarifies the purpose of max_links. Baseline 3 is appropriate given the high schema coverage.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL.' It uses a specific verb ('Generate'), names the resource ('llms.txt'), and defines the action ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format'). This distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on auditing presence rather than generating the file.

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

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

The description provides explicit use cases: 'Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives clear context on when to use the tool. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the return value details but does not disclose potential behaviors like network requirements, authentication needs, or error handling. It doesn't contradict annotations but provides limited extra context beyond what annotations imply.

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

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

The description is a single sentence that front-loads the action ('Get') and resource ('layer's schema'), then lists the exact output elements. Every word earns its place, with no filler or redundancy.

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

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

Given there is no output schema, the description adequately enumerates the return values (fields, geometry type, record count, capabilities), which is sufficient for a schema lookup tool. It does not cover edge cases like authentication or invalid URLs, but for the tool's simplicity, this is reasonably complete.

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

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

The schema has 100% coverage for the single 'url' parameter with a clear description and example. The tool description merely references 'by url' without adding new semantic details about URL format, validation, or accepted service types. With high schema coverage, the baseline score of 3 is appropriate; the description does not further 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 clearly states the tool gets an ArcGIS Feature/Map Service layer's schema by URL, listing the exact return items (fields, geometry type, record count, capabilities). This is a specific verb+resource pair that distinguishes it from sibling tools like query_layer, which likely queries data.

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

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

The description implies usage when you need schema information from a layer URL, which is clear context. However, it does not explicitly mention when not to use it or provide direct alternatives (e.g., query_layer for data), so there is no explicit exclusion but the intended use case is clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds value by clarifying the scope ('caller's active subscriptions') and the specific fields returned, which are not fully evident from the schema alone since no output schema is provided.

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

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

The description is two sentences and front-loads the action, then the return fields, then the use case. Every sentence earns its place with no redundancy or fluff.

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

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

For a simple read-only listing tool with one optional parameter and strong annotations, the description is nearly complete. It states what is listed, when to use it, and what fields are returned. It could mention the include_inactive parameter, but the schema already covers that, so the overall context is sufficient.

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

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

Schema description coverage is 100%, with the include_inactive parameter fully documented. The description does not add additional parameter semantics, but it reinforces 'active' which aligns with the default behavior. Baseline of 3 is appropriate since the schema carries the explanatory burden.

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

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

The description uses the specific verb 'List' with the resource 'subscriptions' and scope 'caller's active', making it clear what the tool does. It also enumerates the returned fields, which avoids ambiguity and distinguishes it from mutation tools like subscribe/unsubscribe.

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

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

The description explicitly states when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context for its use, though it doesn't explicitly name alternatives or describe 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 are all false, so the description carries the full burden. It transparently discloses the claim_token workflow (returns a token, can be passed back later to read status), the rate limit (5 per identifier per day), the impact on roadmap, and that it is free. It also states what the tool does NOT do (fix other vendors' tools), which is valuable 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?

Though longer than typical descriptions, every sentence earns its place: purpose, usage types, exclusion, token workflow, rate limit, and quota. The information is front-loaded and logically structured, making it dense without being wasteful.

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

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

Despite no output schema, the description explains the return behavior (claim_token, status, what changed). It covers context (pack/tool/vertical guidance via 'in terms of Pipeworx tools/packs'), rate limits, and exclusions. The tool's complexity (optional params, token-based follow-up) is fully addressed, leaving no obvious gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning beyond the schema by explaining the claim_token lifecycle ('Filing without an account returns a claim_token; pass it back later...') and giving message guidance ('describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This enriches the parameter understanding, so a 4 is warranted.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates the feedback types (bug, feature/data_gap, praise) and explicitly differentiates from siblings by stating it is ONLY for tools served by this Pipeworx connection, not other MCP servers.

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 for each type: wrong/stale data (bug), missing tool (feature/data_gap), worked well (praise). It also gives a clear exclusion rule ('if the tool came from a different MCP server... file it with that server instead') and an alternative path, making it unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral context beyond these: it reveals caching behavior ('Cached 5min-1h depending on window'), data aggregation source ('derived from CF analytics-engine'), and privacy ('no PII, just (pack, tool, count)'). 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 front-loaded with the core purpose, then returns, then ordered use cases, and finally data provenance and caching. Every sentence contributes distinct information, and the numbered list improves scannability. It is information-dense without being bloated.

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?

Although there is no output schema, the description clearly states the return components (top tools, top packs, total call volume) and the data format ('pack, tool, count'). It also covers caching, privacy, and window behavior. For a simple one-parameter read-only tool, this is comprehensive and sufficient for an agent to invoke correctly.

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

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

The schema description covers 100% of the window parameter, including the default and the semantic difference between short and long windows. The tool description repeats 'recent window' and mentions windows in use cases but adds no new parameter-level details. With full schema coverage, baseline 3 is appropriate.

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

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

The description opens with a clear, specific statement: 'What other AI agents are calling on Pipeworx right now.' It then explicitly lists the returns (top tools, top packs, total call volume) and the recent window. This distinguishes it from sibling tools like discover_tools by focusing on real-time agent call trends rather than general discovery.

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 concrete use cases (hot data sources, canonical choice confirmation, use-case alignment) and explains window trade-offs ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). However, it does not explicitly name alternative tools or state when not to use it, so it falls 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?

The description adds rich behavioral detail beyond annotations: thresholds (>3pp, >20% placeholder, ≥0.30 Jaccard), the live CLOB fill check, null-return conditions, and the exact output shape. It explains that realizable_edge_pp ≤ 0 means the overround is not book-tradable, which is actionable context annotations alone do not provide.

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

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

Despite a long length, the description is structured with clear section labels and examples, every sentence adds new information (modes, filters, fill check, alternative tool). It is front-loaded with the core purpose and then provides necessary detail without 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 complex tool with no output schema, the description fully specifies the response shape, edge cases (null signal, skipped_low_similarity, placeholder filtering), and cross-references the sibling tool for sizing. It covers input modes, behavior, and decision guidance, making it self-sufficient.

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

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

The input schema gives only brief descriptions, but the tool description adds concrete examples ('fed-decision-may-2026'), accepts full URLs, explains how each parameter selects a different scan mode, and defines what 'topic' does with a seed question. This meaningfully enriches the schema.

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

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

The description opens with a specific verb ('Find') and resource ('arbitrage opportunities on Polymarket'), and the method ('monotonicity violations + partition-sum checks') distinguishes it from sibling tools like polymarket_edges or polymarket_fill_risk. It also clarifies three call modes, making the tool's scope unambiguous.

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

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

It explicitly instructs when to use each mode: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', and 'topic for a themed cross-event scan'. It also names an alternative – 'For custom sizing use polymarket_fill_risk' – and warns 'do not trade it' when realizable edge is nonpositive.

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, but the description goes far beyond these by detailing a 1h KV-level cache, the 24h-move warning, why segments may appear empty via _diagnostics, placeholder-slug filters, and the per-sport alpha values. It also explains the rationale behind the min_partition_leg_kelly knob, providing deep behavioral insight.

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 well-structured, front-loading the core purpose in the first sentence and then grouping details into clearly labeled segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.) and response structure. Every sentence adds relevant detail for correct use, though some specifics (like per-sport alpha numbers) are perhaps more than necessary for tool selection and invocation.

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

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

No output schema is provided, so the description carries full burden for explaining return values. It does so thoroughly, listing the top-level response structure (by_segment, fed_candidates, _diagnostics), the fields carried by every opportunity (edge_pp_net, kelly_fraction, etc.), and the meaning of the diagnostic funnel counters. The complexity of a 9-parameter tool with three model families is fully addressed.

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

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

Schema coverage is 100%, and each parameter already has a descriptive schema entry. The description adds extra meaning by explaining how the knobs interact (e.g., 'TRADEABLE-EDGE KNOBS' and why min_kelly doesn't filter partition arb opportunities) and by defining the semantics of 'edge is evaluated NET of slippage'. This elevates the parameter understanding beyond the raw schema.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's purpose ('what should I bet on today') and distinguishes it from siblings by naming the three response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), which differentiates it from other Polymarket tools like polymarket_arbitrage or polymarket_edge_tracker.

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 on when to use the tool: it is for agents that want daily opportunities without paging hundreds of markets, and it covers three families of models. It also explains what is excluded (Fed bets are unreliable and excluded from ranking) and how knobs affect results. However, it does not explicitly name alternative sibling tools or state 'use X instead', so it lacks direct when-not-to-use guidance.

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

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

Beyond the readOnly/idempotent annotations, the description discloses several behavioral traits: snapshots are written only on cache-miss (explaining data gaps), history is bounded by a 60-day TTL, and decay numbers use daily closes of edge_pp_net rather than intraday data. This is substantial context that annotations cannot provide.

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

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

The description is dense but well-structured: it leads with purpose, then args, response format, and limits. Every sentence adds value, and the use of ALL-CAPS labels ('RESPONSE', 'LIMITS') makes it scannable. No wasted words.

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

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

With no output schema, the description fully describes the response structure (tracked[], expired[], snapshot_dates[]) and their semantics. It also covers operational constraints like TTL and data gaps, giving the agent sufficient context to interpret results correctly. Nothing essential is missing.

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

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

Schema coverage is 100%, and the description only restates the parameter defaults (days=14, window='1wk') without adding new semantics. The schema already documents the lookback range, clamp, and window family options, so the description adds no meaningful parameter detail.

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: 'how long has this edge existed and is it shrinking?'. It distinguishes itself from the sibling polymarket_edges tool by focusing on historical persistence and decay rather than raw current edge data.

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

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

The description provides clear context on when to use the tool, such as differentiating a fresh wide edge from a 3-week-old one. It does not explicitly name alternative tools or state when not to use it, but the example and focus on snapshot history make the intended use case obvious.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds rich behavioral context: mode-specific semantics, output fields, size_usd interpretation, and the directional-risk warning. No contradictions.

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

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

Long but well-structured, front-loaded with purpose, and uses explicit mode labels (SINGLE-MARKET, BASKET). Every sentence provides operational value, making it appropriately sized for a complex two-mode 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?

No output schema exists, but the description enumerates all key return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, forced_directional_risk), covering the essential information comprehensively.

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

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

Schema coverage is 100%, but the description adds deeper meaning: defines size_usd behavior per mode, side defaults/options for each mode, and clarifies market vs event usage, going 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?

Clearly identifies itself as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth', specifies single-market and basket modes, and explicitly contrasts with siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use it: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and explains why, citing thin books and partial-fill risk.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral context: the compatibility_warning conditions, temporal alignment impact, skipped leg-pair counters, and the caution that pre-mapped ≠ tradeable. It also explains the response format and edge cases where spreads are meaningless. No contradiction with annotations.

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

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

The description is long but highly structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence conveys a distinct fact, and the warning at the end is essential for correct use. It earns its length, though a slightly tighter opening could improve scannability.

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

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

Given the tool's complexity and the absence of an output schema, the description compensates thoroughly: it documents response structure (leg prices, top_spreads_pp), explains compatibility_warning triggers, temporal_alignment semantics, and skip counters. An agent has everything needed to interpret results and anticipate failure modes.

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

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

The schema covers 100% of parameters with descriptions, giving a baseline of 3. The description adds semantic value by explaining the two modes and how the explicit ticker/slug override the topic mapping, as well as the meaning of the pre-mapped shortcuts. This goes beyond the schema's individual 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 opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It immediately distinguishes from sibling tools (e.g., polymarket_arbitrage) by naming the exact venues and the spread concept. It also details two modes and output, 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 clearly describes the two invocation modes (topic shortcuts vs explicit ticker/slug) and the context for each. It cautions that most pre-mapped topics are not tradeable, setting expectations for when results are meaningful. However, it does not explicitly name alternative sibling tools or state when to choose this over polymarket_arbitrage.

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 return behavior (attribute rows and geometry) and practical guidance for sampling. No contradictions with annotations.

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

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

Four concise sentences, front-loaded with the core purpose, then parameter overview, return type, and a usage tip. Every sentence earns its place with no redundancy.

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

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

Given the absence of an output schema, the description adequately states that it returns attribute rows and geometry. It also covers pagination via offset and provides sampling guidance. The integration with search_datasets is mentioned, making it reasonably 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% with descriptions for all six parameters, so the schema handles parameter semantics. The description adds a high-level mention of SQL-like where, comma-separated out_fields, etc., but does not meaningfully exceed the schema's detail.

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/Map Service layer by URL, with a specific verb and resource. It distinguishes from sibling tools like search_datasets (finding datasets) and layer_info (likely metadata) by focusing on data retrieval.

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 context that the URL comes from search_datasets and gives a sampling tip ('Use where="1=1" + out_fields="*" to sample'). It does not explicitly name alternatives or exclusions, but the usage context is clear for a data-query 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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond annotations, such as the scoping rule ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the dual behavior of listing all keys when the key argument is omitted. No contradictions with annotations.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence contributes essential information: behavior, usage context, and scoping. No fluff or redundancy, achieving high clarity in minimal space.

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 strong annotations and no output schema, the description is complete. It covers the core behavior, optional argument semantics, scoping restrictions, and integration with sibling tools (remember/forget). There are no significant gaps for an agent to invoke it correctly.

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

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

Schema coverage is 100%: the 'key' parameter already has the description 'Memory key to retrieve (omit to list all keys).' The tool description reinforces this omit-to-list behavior and adds illustrative examples of key values (user's target ticker, address, notes), slightly enriching the semantics but not substantially beyond the schema.

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

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

The description opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes from siblings like remember and forget by stating the action and the optional key omission behavior. The examples of saved context (ticker, address, research notes) further clarify the tool's purpose.

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

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

The description explicitly states when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also provides alternative-related guidance by pairing with 'remember to save, forget to delete,' effectively naming sibling tools and indicating complementary usage.

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

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

Annotations affirm a read-only, idempotent, non-destructive profile. The description goes beyond by disclosing the mark_read side effect that flags events read so subsequent calls only show newer ones, and by detailing the payload fields. The mark_read nuance is transparently described, and since the description does not contradict the annotations, no contradiction is flagged.

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 efficient sentences: purpose, payload components, and usage/modification semantics plus an alternative endpoint. Every sentence earns its place with no redundant filler.

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

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

With no output schema, the description compensates by specifying exactly what each alert contains (source, citation_uri, raw payload) and how mark_read affects subsequent calls. Combined with full schema coverage and relevant annotations, an agent has all the needed context 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?

All 5 parameters have schema descriptions (100% coverage), so the baseline is 3. The description adds extra meaning through a concrete type example ('sec_8k'), clarifying since as an ISO timestamp, and explaining the stateful consequence of mark_read. This enriches the user's 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 'Pull fired events from your subscription feed', which is a specific verb+resource statement. It then elaborates on unique output ('most recent alerts the evaluator has written to your persisted feed') that clearly distinguishes it from sibling tools like list_subscriptions and recent_changes.

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 clear context: use to fetch fired alerts from the feed, filter by type/since, and polling is explicitly endorsed ('Polls work fine'). It also mentions an alternative REST endpoint for scripts, but does not reference sibling MCP tools or state when not to use it, so it stops short of full alternative guidance.

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

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

Annotations already declare readOnly/idempotent; description adds significant source-specific behavior: GDELT preferred with GNews fallback on rate limit/5xx, USPTO PatentsView sunset causing soft-fail, parallel single-call fan-out, and output structure with citation URIs. No contradictions with annotations.

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

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

Description is a dense single paragraph covering many details without redundancy, but it is longer than minimal and uses run-on structure. Every sentence earns its place, though a more structured format could improve readability.

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

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

For a multi-source aggregator with no output schema, description fully discloses sources, fallback behavior, time window semantics, and return shape (changes[], total_changes, citation URIs), plus mentions the alternative tool. Complete given 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 covers all 3 parameters at 100%, including `since` format examples and `value` ticker/CIK. Description only restates `since` usage and doesn't add substantial new semantics beyond schema, so baseline 3 is appropriate.

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

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

Description clearly defines it as a change feed for a company over a time window, listing specific sources (SEC EDGAR, GDELT/GNews, USPTO). It explicitly distinguishes from entity_profile, making the tool's purpose unambiguous and differentiating it from a key sibling.

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 example natural language queries ('What's new with X'), explicitly states when to use (recent change inquiries), and directs users to entity_profile for static profiles regardless of window. This offers clear when/when-not guidance.

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

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

The description reveals key behavioral traits beyond annotations: key-value pair scoped by identifier, persistence differences between authenticated users and anonymous sessions (24-hour retention), and pairing with recall/forget. These details are not present in the annotations, which only declare idempotentHint=true and other hints. No contradiction exists between description and 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 moderately long but every sentence carries meaningful information: the core action, when to use it, storage mechanics, retention specifics, and relationship to sibling tools. The main verb appears in the first sentence, and the structure is logical, flowing from purpose to use cases to implementation details.

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

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

For a simple two-parameter tool with no output schema, the description covers all relevant context: what it does, when to use it, how persistence works, and how it relates to recall and forget. It provides sufficient information for an agent to decide when to invoke this tool and what to expect from the behavior. The absence of an output schema is acceptable because the tool likely returns a simple confirmation or void.

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

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

The input schema already provides full descriptions for both parameters (key with example, value with allowed content), giving 100% schema coverage. The description reinforces the key-value pairing and storage context but does not add new parameter semantics beyond what the schema describes. Baseline 3 is appropriate when schema fully covers parameters.

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

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

The description opens with a clear verb and object: 'Save data the agent will need to reuse later.' This establishes the tool's purpose as a memory store. It also distinguishes itself from siblings by explicitly mentioning 'Pair with recall to retrieve later, forget to delete,' differentiating the write operation from related read/delete 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 guidance on when to use the tool: 'Use when you discover something worth carrying forward' and gives concrete examples (resolved ticker, target address, user preference, research subject). It also names complementary tools (recall, forget) and explains the storage approach, making it clear when this tool is the right choice versus alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds critical behavioral context: cascading internal lookups (replacing 2-3 manual steps), graceful degradation of LEI/FIGI, and explicit reporting of unresolvable identifiers. 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?

Description is packed with valuable information but somewhat dense; it could be slightly more structured (e.g., bulleted list of supported types) for easier scanning by an agent. However, it front-loads the most critical use-case examples and guidance.

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

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

Given no output schema, the description compensates fully by detailing return behavior (every identifier labelled with source, unresolved identifiers listed explicitly). Covers input parsing, fallback behavior, and internal complexity, making the tool's full capability transparent.

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

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

Schema coverage is 100% and both parameters (type, value) are documented, but the description adds significant nuance for the 'value' parameter (accepts ticker, CIK, ISIN, or name for company; brand or generic for drug) and explains how ISIN resolves to legal entity, going beyond the schema's brief description.

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

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

The description clearly states the tool resolves user-spoken names (company, drug) to canonical identifiers required by other tools, listing exact example queries and explicitly distinguishing it from siblings like 'compare_entities' and 'entity_profile' by explaining it provides a comprehensive identity resolution.

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 guides when to use ('Use FIRST whenever you have a name but need an ID'), details supported types, and describes graceful degradation behavior when upstream services fail, letting the agent know trade-offs without needing to list 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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context: it internalally probes each entity via ai_visibility_check, ranks results, and surfaces most/least recognized. This goes beyond the annotation-only safety profile and explains the tool's operational behavior.

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

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

Three sentences, front-loaded with the main purpose and action. Every sentence contributes: purpose, method (probes with ai_visibility_check), use case, and return value. No filler or repetition.

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

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

The tool is moderately complex (4 params, no output schema), but the description compensates by specifying the return structure (ranked list with score, confidence, signal density) and explaining the internal workflow (probes via ai_visibility_check). It omits edge-case details like model-specific behavior, but the schema covers parameter constraints.

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

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

Schema description coverage is 100%, so all four parameters are already documented with descriptions. The tool description adds no new parameter-level semantics beyond what the schema provides (e.g., 'entities' as brands/competitors). Baseline of 3 is appropriate because the schema handles parameter meaning.

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

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

The description clearly states a specific action: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes from sibling tools like ai_visibility_check (single entity) by emphasizing side-by-side comparison and ranking, and identifies the output (ranked list with score/confidence/signal density).

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

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

The description gives a clear use case: 'competitive AI-marketing audits' with a concrete example question. It implies this tool is for multi-entity comparison, contrasting with single-entity tools, but does not explicitly name alternative tools or state when not to use it. Slight gap in explicit exclusionary 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, idempotent, non-destructive), the description discloses important runtime behavior: 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out', and the 'NPM ecosystem only in v1' limitation. This gives the agent actionable expectations about timeouts and partial results. 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 information-dense but well-structured, with a clear logical flow: purpose, usage triggers, return summary, ecosystem limitation, and failure behavior. Every sentence adds value; no filler or redundancy.

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

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

Given the tool's complexity (composite call across two external services), the description is richly complete. It enumerates the return fields, lists failure modes, specifies ecosystem scope, and provides timing expectations. Since there is no output schema, the description fully compensates by describing the output structure.

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 (package, version) with clear descriptions, including the default behavior of 'version'. The description adds context about how the parameters are used (e.g., comparing to latest) but does not provide new syntactic details. With schema coverage at 100%, a score of 3 is appropriate per the calibration guidelines.

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: 'Composite "should I add this npm package to my project" check in ONE call' and lists the data sources (deps.dev, bundlephobia) and exact outputs (license, advisories, bundle size, etc.). This clearly defines the tool's function and distinguishes it from any sibling tools, none of which perform this kind of package assessment.

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

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

The description explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives an exclusion and alternative: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', telling the agent to use a different path for non-npm ecosystems. This is exemplary usage guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds the output contract: returns name, summary, record_count, owner/org, and url, plus the link to follow-up tools. It doesn't mention rate limits or errors, but annotations lower the bar.

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: one for purpose, one for output and next steps. No redundant information, fully 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 no output schema, the description specifies all returned fields, so the agent knows what to expect. It also explains how to chain with query_layer/layer_info. Combined with rich annotations and complete schema, the tool is fully understood.

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 cover 100% of parameters (limit, query, org_id). The description reinforces 'by keyword' but doesn't add new meaning beyond the schema's detailed parameter descriptions, so baseline 3 applies.

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

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

The description clearly states the tool searches City of Fontana GIS open geospatial datasets by keyword, explicitly listing example categories and the return payload. This distinguishes it from siblings like query_layer and layer_info, which operate on a specific dataset URL.

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 instructs to pass the returned Feature Service `url` to query_layer or layer_info, effectively telling the agent when to use this tool (to find datasets) and what to do next. It implies that if you already have a URL, you should skip this and go to the downstream 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description reveals return format (passages, character offsets, similarity scores), the underlying embedding model (BGE-base-en) and chunking strategy (500-char overlapping windows), and a hard limit (200K chars with truncation flag). This is substantial extra 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 the core purpose and then layers on usage context, a sibling integration, and technical details. It is dense but every sentence contributes value; only slight improvement could come from tightening the final sentence.

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

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

With no output schema, the description adequately covers the return format (top-N passages with offsets and scores) and operational limitations (200K char cap, truncation flag). It also includes use-case guidance and integration with a sibling tool, making it a complete standalone description.

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

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

The input schema already describes all three parameters (text, query, limit) with 100% coverage, so the baseline is 3. The description restates that text is pre-fetched and query is natural-language, but adds no new parameter-level details beyond what the schema provides.

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

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

The description starts with 'Semantic search INSIDE a fetched record,' which clearly identifies the action, target, and scope. It further distinguishes from sibling tools by emphasizing that it works on already-fetched text and returns passages with offsets, making it complementary to but different from tools like ask_pipeworx_grounded.

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

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

The description gives an explicit usage condition: 'Use when the record is too big to cram into the prompt.' It also names a sibling tool (ask_pipeworx_grounded) and explains the recommended pairing, providing clear guidance on when to use this tool versus 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=false, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context beyond these: OAuth persistence requirement, SMS 10/day cap, phone verification need, and the always-on feed behavior. It does not explicitly mention webhook auto-disable (present in schema) or idempotency effects, but the annotations cover safety and the description adds meaningful constraints.

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

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

The description is dense but well-structured: it front-loads the core purpose, then uses colons and examples to explain types and delivery channels. Every sentence contributes actionable information, including prerequisites and constraints. It is somewhat long, but given the tool's complexity (3 params, nested objects, multiple types), the length is justified 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?

With 3 parameters, nested objects, 5 enum types, and no output schema, the description covers the key return value (subscription id), authentication prerequisites, channel options, and per-channel constraints (e.g., SMS cap, phone verification). It does not detail error scenarios or idempotency semantics, but annotations cover idempotency and the schema details webhook secrets. Overall, it provides enough context for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description enhances parameter understanding by giving concrete usage examples for sec_8k, polymarket_edge, and fred_series, and explains item code semantics (e.g., items:["5.02"] = officer change). It omits examples for patent_grant and clinical_trial, but the schema's per-parameter descriptions fill that gap, so the overall contribution is 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?

Description opens with 'Create a proactive monitoring subscription to a live-data event stream' – a specific verb and resource that clearly distinguishes from siblings like list_subscriptions and unsubscribe. It also enumerates supported types (sec_8k, polymarket_edge, fred_series) and delivery channels, leaving no ambiguity about the tool's function.

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

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

Provides clear context on when to use: for proactive monitoring, and defines prerequisites (OAuth account required, anonymous/BYO cannot persist) and delivery options (feed always on, optional email/sms). It implicitly contrasts with recent_alerts by explaining that feed events are pulled via recent_alerts or a URL. However, it doesn't explicitly name alternative tools or state when NOT to use it, so it falls short of a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the description need not restate safety. It adds valuable behavioral detail beyond annotations: returns category-bucketed examples, includes exact tool+argument shapes, draws from the live catalog, and supports optional topic filtering. This is useful and consistent with 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 longer than average but each section earns its place: natural-language trigger phrases, outcome description, parameter behavior, and explicit when-to-use. It is front-loaded with user-facing phrasings and structured with dashes, making the information scannable. Slight redundancy in topic category lists keeps it from 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?

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers the return content, categories, usage modes, and onboarding context. It explains what the user gets back (bucketed examples, tool mapping) and when to use it, which is sufficient for reliable invocation.

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

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

The schema already documents the single optional `topic` parameter with 100% coverage, so the baseline is 3. The description enriches this by giving concrete examples like 'finance', 'pharma', 'betting' and clarifying that omitting the topic returns a cross-category spread, adding practical meaning beyond the schema.

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

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

The description clearly identifies the tool as 'the onboarding entry point' that returns category-bucketed example questions with the exact tool and argument shape to answer them. It distinguishes itself from siblings like discover_tools and ask_pipeworx by explicitly positioning its role as teaching what to ask and how to call meta-tools.

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

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

The description gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains call variants (no arguments vs. topic). However, it does not explicitly state when not to use it or name specific alternative tools, so it stops short of a perfect score.

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

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

Annotations already indicate non-destructive and idempotent behavior. The description adds critical context: ownership enforcement, deactivation (not deletion), and preservation of history via recent_alerts, which aligns with destructiveHint=false and enriches the behavioral 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?

Two sentences, front-loaded with purpose, and every sentence adds value without redundancy. The structure is efficient and easy to parse.

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

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

For a simple tool with one parameter and rich annotations, the description covers scope, behavior, and consequences. The reference to recent_alerts provides a meaningful link to related functionality, making it 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 single parameter id is fully described in the schema ('Subscription id returned by subscribe'), so the description adds no new parameter semantics. Baseline 3 applies since schema coverage is 100%.

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

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

The description opens with 'Cancel a subscription by id,' a specific verb+resource pairing that clearly states the tool's function. It distinguishes itself from sibling tools like subscribe and list_subscriptions by focusing on cancellation.

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 clarifies when to use the tool (to cancel a subscription by id) and includes an important ownership constraint. However, it does not explicitly mention alternatives or when not to use it, though the context is clear.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds substantial context: the exact verdict values, the critical distinction between could_not_verify (check didn't happen) and unsupported (no source), the verification_error{stage,detail} payload, and the warning not to treat could_not_verify as evidence. It also reveals the citation format and the routing logic. This exceeds 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?

The description is long but every sentence earns its place: examples, usage rule, two-path routing, return contract, cautionary note, and efficiency claim. It is front-loaded with the most recognizable query patterns, and there is no fluff or repetition of schema details.

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

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

Given the tool's complexity (two pipelines, multiple verdicts, error cases) and the absence of an output schema, the description covers all essential aspects: what it returns (verdict, value, citation, reasoning), how it routes, what could_not_verify vs unsupported mean, and the replacement benefit. An agent has enough to select and invoke it correctly without further clarification.

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

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

Schema coverage is 100% for both parameters (claim and tolerance_pct), so baseline is 3. The description adds meaningful guidance: example claims, default tolerance implied by wording capped at 5, and a concrete use case (set 1–2 for hallucination detection). This goes beyond the schema's 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 opens with natural-language query examples and explicit verbs like 'fact check' and 'verify', then states the tool's purpose: checking whether a user's claim is factually correct. It clearly differentiates from siblings by describing its dual-path behavior (SEC/XBRL for financial claims, grounded pipeline for everything else), 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?

Explicitly instructs 'Use whenever the agent needs to check whether something a user said is factually correct,' and notes that non-financial claims automatically fall through to the grounded pipeline, implying full coverage. It also mentions the tool replaces 4–6 sequential calls, positioning it as the go-to option. However, it does not name alternatives or state when not to use it, so it falls short of full marks.

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