Arcgis Asheville

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

The annotations already indicate a safe, read-only, idempotent operation. The description adds valuable behavioral details: the default free model (Workers AI Llama-3.3-70b), the requirement for a BYO Anthropic API key with direct billing, the return structure (per-model score/confidence/signals/raw_response + combined view), and the default behavior when 'models' is omitted. This goes beyond the annotations to explain cost implications and response contents.

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 function, then defaults, return format, and use cases. Every sentence contributes value without redundancy or fluff. It is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (multiple models, optional API key, defined output structure) and the absence of an output schema, the description covers all essential aspects: purpose, parameters, return format, default behavior, and use cases. It is sufficiently complete for an agent to invoke the tool correctly without further clarification.

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

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

The input schema already provides 100% parameter descriptions, so the baseline is 3. The description adds meaningful nuance by explaining the billing impact of '_apiKey' (you pay Anthropic directly) and reinforcing the default model behavior. It also clarifies the 'entity' scope with examples of business/brand/product/topic, which complements the schema's examples.

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

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

The description clearly states the tool's function: probing one or more LLMs for their knowledge about an entity and scoring visibility on a 0-100 scale. It specifies the resource (LLMs), the action (probe/score), and the output format. Though it doesn't explicitly name a sibling alternative, the concept of scoring LLM visibility per model is distinct from the other sibling tools like ask_pipeworx or 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?

The description provides clear use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and context on when the tool is valuable. It does not explicitly state when to avoid it or point to alternatives, but the context is sufficient for an agent to decide when to use it.

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

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

Beyond the read-only/idempotent annotations, the description discloses that the tool routes to 5,462 tools, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, and works on every tier. It also indicates it makes 'one fast call'. This adds meaningful behavioral context not present in annotations.

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

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

Though the description is lengthy, every sentence serves a purpose: it front-loads the key directive ('PREFER OVER WEB SEARCH'), provides structured guidance ('START HERE', 'Step up only when needed'), and offers concrete examples. The organization makes it easy to scan, and the density is justified given the tool's role as a universal router.

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

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

Given the tool's complexity and lack of output schema, the description covers the essential context: what it does, when to use it, what it returns (structured answer with citations), and how it compares to siblings. It also notes that it works on all tiers and makes one fast call, which is useful operational context. No gaps are apparent.

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

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

The schema already provides 100% coverage with a clear description for 'question', including alias information. The tool description further enhances this by giving many real-world example questions (e.g., 'current US unemployment rate', 'adverse events for ozempic') and clarifying that the question can be a natural language request, which adds value beyond the schema.

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

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

The description clearly states the tool's role as a default entry point for factual questions, listing many specific domains (SEC filings, FDA data, FRED, USPTO, etc.) and explicitly distinguishing it from siblings like ask_pipeworx_grounded and deep_research. The verb 'routes' plus the resource (5,462 tools) makes the function highly specific.

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

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

The description explicitly instructs 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', with clear conditions for when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions). It also gives concrete example queries and covers breaking news use cases, making the selection criteria highly actionable.

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

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

The description goes well beyond the annotations by disclosing the beta status, the fact that no candidate is currently active (as of 2026-07-26), that it currently matches ask_pipeworx exactly, and that it is a full working router rather than a fallback. This is rich behavioral context that annotations alone do not provide.

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

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

The description is three sentences long, each serving a distinct purpose: defining the tool, stating the current state, and giving usage guidance. It is front-loaded and free of 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?

For a router with no output schema, the description adequately covers what the tool does, how it relates to the stable version, when to use it, and what the current operational status is. It also clarifies the response shape is the same as ask_pipeworx, making the description 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 schema already provides 100% coverage with descriptions for all six parameters (question plus aliases). The description adds no new parameter-level semantics beyond referencing 'same arguments' as ask_pipeworx, which is minimal additional value.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, describes it as a universal router with the same tools, arguments, and response shape, and distinguishes it from the stable ask_pipeworx and the sibling ask_pipeworx_grounded. The verb 'ask' and the resource 'pipeworx' are evident, and the experimental edge is stated.

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 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide what merges. This provides clear when-to-use guidance, though it does not explicitly mention when not to use it (e.g., production).

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), the description reveals important behaviors: it returns a structured answer with a verbatim evidence quote, and it explicitly refuses with a machine-readable refusal_reason when the data doesn't answer. It also discloses the extra LLM call cost and that it uses ONLY the tool result, which is critical for trust.

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 typical, but every sentence provides meaningful value: purpose, routing, output format, use cases, and cost trade-off. It is front-loaded with the core purpose and uses bullet-like structure (the refusal reasons and success payload) that aids scanning. Slightly verbose but not 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 lacking an output schema, the description fully specifies the return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and all possible refusal reasons. It also covers the tool's routing scope, cost implication, and ideal use cases. No essential missing context for an agent to use 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% and all parameters are aliases for 'question', so the schema already fully explains them. The description adds little beyond 'fills arguments,' which is generic. Given the simplicity of a single natural-language question, a baseline 3 is appropriate.

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

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

The description opens with a specific, differentiated purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly states the verb (answer), the resource (pipeworx), and the distinguishing trait (grounded extraction from tool results). It also contrasts with the sibling 'ask_pipeworx' by emphasizing extra safety for quoted or cited answers.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' with concrete examples. It even gives a when-not-to-use rule: 'prefer ask_pipeworx for casual lookups.' This directly addresses alternatives among sibling tools, making the selection decision clear.

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

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

The description goes far beyond annotations by disclosing fan-out behavior, classifier list, response shapes, resolver contract (market_match_confidence, alternatives), parent_event extractor, news fallback handling, safety short-circuit paths (low_confidence_match, market_closed_or_inactive), and resolution-rule risk (refund_50_50, etc.). It also explains the open-world/idempotent nature implicitly. No contradictions with the readOnlyHint/idempotentHint annotations.

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

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

The description is long but well-structured with capital-letter headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.), making it easy for an agent to scan. Each section adds distinct behavioral or safety information that is not available in the schema or annotations. There is no fluff; every block covers a real use case or edge case.

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

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

There is no output schema, but the description compensates thoroughly by detailing the exact response shapes (result.market, result.analysis, result.evidence), the resolver contract, safety statuses, and resolution-rule risk parsing. It also explains fallback behavior for news sources and how to interpret confidence levels. This is complete enough for an agent to invoke and interpret results correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining how 'depth' maps to fan-out scope (quick vs thorough) and how 'include_raw' influences response size and usability, plus examples of market input formats. It enriches the parameter semantics beyond the schema's short descriptions.

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

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

The description starts with a specific verb+resource ('Research a Polymarket bet') and clearly explains the tool's end-to-end flow (resolve, classify, fan out, return evidence packet + market-vs-model comparison). It distinguishes itself from sibling tools like polymarket_edges and deep_research by focusing on per-bet research with Pipeworx data, not general research or edge lists.

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"'. Fan-out examples (BTC, Fed, Hormuz, Yankees, etc.) further clarify when to use it. However, it does not explicitly mention when NOT to use it or name alternative tools (e.g., polymarket_edges) for different needs, so it falls just short of a 5.

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

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

The description discloses behaviors beyond the read-only annotations: it pulls latest 10-K data for companies, FAERS/FDA/trial counts for drugs, handles off-calendar fiscal years correctly, sorts results by a primary metric, and returns paired data with citation URIs. This adds significant operational context and is fully 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 compact yet information-dense, leading with trigger phrases and the core promise, then detailing type-specific behavior and output. Every sentence contributes value, covering usage, data sources, sorting, and return format without unnecessary filler.

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

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

Given only 2 parameters and no output schema, the description provides a complete picture: what the tool does, what data it retrieves per type, how results are sorted, what is returned (paired data + citation URIs), and why it is preferred over alternatives. No critical contextual gaps remain.

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

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

Schema coverage is 100%, and the description adds substantial semantic meaning: it specifies exact fields pulled for type='company' (revenue, net income, cash, long-term debt) and type='drug' (FAERS counts, FDA approvals, trial counts), plus examples for values. This goes far beyond the schema's basic parameter descriptions.

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

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

The description uses a specific verb ('compare') and resource ('companies or drugs'), and clearly defines the scope as side-by-side comparison of 2–5 entities in one parallel call. It distinguishes this tool from sequential single-pack lookups, so an agent can immediately identify its purpose.

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

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

Explicit trigger phrases ('Compare X and Y', 'X vs Y', 'rank these companies') and an explicit preference rule ('ALWAYS PREFER over sequential single-pack lookups') give clear when-to-use guidance. It also distinguishes between company and drug types and what data each pulls, so the agent knows which type to select.

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 adds substantial context: account/payment gating, parallel routing to 5,462 tools, findings packet structure, gaps[] never invented, second-hop iteration, citation_uri resolvability, contradictions[], and semantic excerpting. These details go far beyond the annotations and provide comprehensive behavioral disclosure.

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 carries essential operational or behavioral guidance. It is front-loaded with the most critical caveat (account required) and proceeds logically. While a bulleted structure could improve scannability, the prose is efficient for the tool's complexity.

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

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

With no output schema, the description must explain the return packet and does so thoroughly: verbatim evidence, confidence, source, fetched_at, gaps[], contradictions[], hop field, and citation_uri. It also covers auth, use cases, alternatives, performance expectations, and citation integrity. This is complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by providing example questions ('compare X and Y's regulatory + financial exposure') and clarifying that broad/multi-part questions are appropriate. It also reinforces depth-specific costs and behaviors, though these are mostly covered in the schema already.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... in ONE call'. It clearly differentiates from siblings with explicit contrasts to ask_pipeworx for single lookups and current-news topics, and even emphasizes it is 'NOT open-web search'.

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

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

It explicitly states when to use the tool: 'Best for broad/multi-part questions over structured data' with examples, and provides clear alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also notes account requirements and fallback behavior if not signed in.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it discloses the return format (names, descriptions, full input schemas with curated examples) and that results are 'ready to call directly, no second schema lookup needed.' This improves transparency without contradicting annotations.

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

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

The description is well-structured: it opens with a concise purpose statement, follows with when-to-use guidance, then explains the return format and a strategic tip. The list of domains is a bit long but serves to illustrate the tool's coverage. Every sentence adds value, 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?

The tool has no output schema, but the description fully explains what the caller can expect: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' It also covers usage context and capability scope, making the description complete for effective tool selection and invocation despite the absence of an output schema.

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

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

Schema description coverage is 100%, so the schema already documents all parameters (query, q, limit, etc.) with clear descriptions and examples. The description adds minimal parameter-specific information beyond what the schema provides; it mentions 'top-N' but does not explicitly link to the limit parameter, though the schema does. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the resource (tools available in the system) and the action (browse/search/look up/discover), distinguishing it from sibling tools by positioning it as a discovery meta-tool rather than a data-specific lookup tool.

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

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

The description 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).' This implies alternatives (using specific tools directly) and provides a clear usage strategy.

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, and the description adds substantial behavioral context: fan-out across SEC, XBRL, USPTO, news, GLEIF; soft-fail for the USPTO patents API; GDELT→GNews fallback; and return structure. This goes well beyond the annotations to disclose limitations and fallback behavior.

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

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

The description is dense but front-loaded with example prompts and a clear functional summary. Every clause serves a purpose, but it could be more readable with separate sections for returns, constraints, and fallbacks. It is appropriately sized for the complexity.

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

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

Given the multi-source fan-out complexity and absence of an output schema, the description thoroughly documents inputs, return fields (including format like zero-padded CIK and sorted fundamentals), and constraints. It also notes the patents API sunset, making it complete enough for an agent to use correctly.

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

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

The input schema already has 100% coverage, including an enum for type and detailed descriptions for value with examples. The description repeats the ticker/CIK guidance but does not add new semantic information beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it produces a full cross-source profile of a US public company in one parallel call, listing specific sources and return fields. It distinguishes itself from sibling tools by explicitly preferring it over chaining single-pack lookups and referencing resolve_entity for name 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?

The description explicitly instructs to prefer this tool over chaining single-pack SEC/XBRL/news lookups when a holistic view is requested, provides example user prompts, and warns that names are unsupported and to use resolve_entity first. This gives clear when-to-use and 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to restate deletion. It does add context about what gets destroyed ('previously stored memory') and why (stale context or sensitive data), but it doesn't disclose additional behaviors like error handling or whether it works on non-existent keys. This is adequate given the annotations, but not rich.

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 short sentences with the core action front-loaded. Every sentence earns its place: the action, the usage context, and the relationship to related tools. No filler or redundant detail.

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 required parameter, no output schema, and annotations covering the destructive/idempotent behavior, this description fully covers the operational context. It explains why to use it and how it fits into the remember/recall/forget workflow.

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

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

Schema coverage is 100% with a clear 'key' description: 'Memory key to delete'. The description's 'by key' reinforces the parameter's role but adds no new semantic detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description starts with a specific verb+resource: 'Delete a previously stored memory by key.' This clearly distinguishes it from sibling tools like remember (store) and recall (retrieve), and the key-based scoping makes the action 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 states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data.' It does not explicitly state when not to use it or name alternative tools, but the pairing suggestion with remember and recall provides useful relational context.

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

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

Annotations already establish readOnlyHint=true and idempotentHint=true, and the description adds useful process detail: it fetches the page, extracts title/description/key links, and emits a text blob. This explains the tool's behavior beyond the annotations without contradicting them.

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

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

The description is three sentences: the first states the core purpose, the second details the process and output, and the third lists use cases. Every sentence adds value; no unnecessary 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?

With only 2 parameters and no output schema, the description fully covers what the tool returns: a single text blob in standard llms.txt markdown. It also gives practical scenarios, making the tool's role clear even without additional structured context.

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

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

The schema provides 100% coverage for both parameters (url and max_links) with full descriptions. The tool description does not add extra parameter semantics, so it meets the baseline but doesn't exceed it.

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

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

The description clearly states the tool's purpose: 'Generate a production-ready llms.txt file for any URL' with a specific verb and resource. It also specifies the output format (standard llms.txt markdown) and differentiates from siblings by framing both project drafting and competitor auditing use cases.

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

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

The description lists concrete use cases ('getting a client's site indexed,' 'drafting llms.txt for your own project,' 'auditing how an AI crawler would see a competitor'), giving clear context on when to use the tool. However, it does not explicitly mention when not to use it or name alternative tools.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable transparency by specifying the output contents (fields, geometry type, total record count, capabilities), which goes beyond the annotation hints. It doesn't mention error handling or URL validity, but for a simple read tool this is adequate.

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 purpose and lists the key outputs without any filler. Every word contributes meaning, making it highly concise and well-structured.

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

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

For a one-parameter, read-only tool with full schema coverage and rich annotations, the description is complete. It enumerates the exact return values (fields, geometry type, count, capabilities), which is sufficient since no output schema exists. The tool's simplicity means no additional context is necessary.

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 fully covers the 'url' parameter with a type, example, and explanation. The description's mention of 'by url' adds no new semantics beyond the schema. Since schema_description_coverage is 100%, the baseline of 3 is appropriate; the description doesn't need to compensate.

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

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

The description uses a specific verb ('Get') and identifies the resource ('an ArcGIS Feature/Map Service layer's schema'), clearly stating what the tool does. It enumerates the exact information returned (fields, geometry type, record count, capabilities), which distinguishes it from siblings like query_layer that would fetch 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 needing layer schema information, but it does not explicitly state when to use this tool versus alternatives like query_layer or search_within. No exclusions or alternative tool recommendations are provided, leaving the agent to infer the appropriate context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, establishing the safe read-only nature. The description adds important behavioral context by specifying that it lists only the caller's active subscriptions and by listing the returned fields. It also implies a default of excluding inactive subscriptions, though this is explicitly handled by the schema parameter. 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 two sentences: first sentence states the core action and return structure, second sentence gives practical usage guidance. It is front-loaded, concise, and every sentence adds value 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?

Even without an output schema, the description explicitly lists the return fields, covering return value expectations. Annotations cover safety and idempotence, the param is documented, and usage guidance is provided. For a simple listing tool, this is complete and actionable.

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 with a clear description for the include_inactive parameter, so the description doesn't need to add parameter semantics. The tool description adds no parameter detail beyond what the schema already provides, matching the baseline for high schema coverage.

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

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

The description uses the specific verb 'List' with the resource 'subscriptions', clearly indicating it retrieves the caller's active subscriptions. It also enumerates the return fields, making the tool's purpose unambiguous. It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on viewing existing subscriptions.

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: 'review what you're monitoring before adding more or to find an id to cancel.' This directly tells the agent when to invoke this tool relative to subscribe/unsubscribe operations, effectively covering both when-to-use and the alternative scenarios.

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

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

Annotations only carry false hints, so the description carries the transparency burden. It discloses rate limiting (5 per identifier per day), that it is free and doesn't count against quota, and the claim_token workflow for later follow-up. This is exactly the kind of behavioral context agents need.

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

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

While a single dense paragraph, every sentence earns its place: purpose, use cases, exclusion rule, message format guidance, claim_token mechanics, team process, and rate limit. There is no filler or redundancy; the structure is compact and front-loaded.

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

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

Covers the complete end-to-end workflow: what to report, when to report, how to format the message, what to expect (claim_token), how to follow up later, and constraints. Even without an output schema, the agent knows what the tool returns and how to interact with it. This is comprehensive for a 4-param tool with nested context.

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

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

Although the schema covers all 4 parameters (100% coverage), the description adds crucial usage semantics: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' It also explains claim_token's subscription-like behavior with an explicit invocation example, going well 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 an explicit, specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes itself from siblings by stating it is ONLY for tools served by this Pipeworx connection, while other MCP servers' tools should be reported elsewhere.

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 when' conditions mapping feedback types (bug, feature/data_gap, praise) to situations, and an explicit exclusion: if the tool came from a different MCP server, file it there instead. It also gives a decision rule for uncertainty ('Not sure? Pipeworx tool names are the ones this connection lists').

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds significant context beyond annotations: caching behavior (5min-1h), data provenance (CF analytics-engine), privacy (no PII), and output shape (pack, tool, count). This is exactly the kind of extra behavioral detail that helps an agent reason about freshness and trust.

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 core purpose, followed by concrete use cases and operational details. Every sentence earns its place, no redundant phrasing, and the structure is easy to parse quickly.

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

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

For a one-parameter tool with no output schema, the description covers what it returns, use cases, data source, caching window, and privacy. This is fully sufficient for an agent to decide when and how to call 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% for the single parameter `window`, and the schema description already explains 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' The tool description only echoes the window option without adding new semantic detail, 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?

States precisely what it does: returns top tools, top packs, and total call volume over a recent window. The opening 'What other AI agents are calling on Pipeworx right now' gives a clear conceptual frame. Distinguishes from siblings as an aggregate usage signal rather than an entity lookup or tool directory.

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

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

Provides three explicit 'Useful for' scenarios (hot data sources, confirming canonical choice, aligning with agent needs), which effectively tells when to use it. Does not explicitly name sibling alternatives or state 'when not to use,' but the phrase 'before asking your own question' strongly implies ask_pipeworx as the 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 declare readOnlyHint and idempotentHint, but the description adds substantial behavioral context beyond those: mode-dependent behavior, semantic similarity threshold (≥0.30 Jaccard), placeholder filtering (>20% returns null), and fill-check pricing against live CLOB depth with the explicit 'do not trade it' guidance. No contradiction with annotations exists.

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

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

The description is long, but the tool is complex with three distinct modes and multiple safety checks. It is structured with caps-lock section markers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that make it scannable. Every clause carries operational value; no filler is present.

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

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

With no output schema, the description compensates by detailing the response shape: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'partition_check{...}'. It also covers fill risk, no-arg default behavior, and cross-event edge cases, making it complete for a tool of this complexity.

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

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

Although schema coverage is 100%, the description enriches each parameter considerably: it explains what `event` slugs look like (with examples), that full Polymarket URLs are accepted, what `topic` means as a seed question, and how each mode affects the scan. This goes far 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 a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three invocation modes (no args, event, topic) and explicitly points to sibling polymarket_fill_risk for custom sizing, making it unmistakable from related tools like 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?

Usage guidance is explicit and prescriptive: 'Call with NO args for a `trending_scan`...', 'pass `event` for...', 'or `topic` for...'. It even provides recommended mode ('event (recommended for a specific market)') and warns when a signal should not be traded. It also names the alternative for custom sizing, satisfying the when-to-use vs alternatives test.

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

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

Adds substantial behavioral detail beyond the annotations: response structure with segments, model family grouping, the 24h-move warning, the Fed bet exclusion rationale, the cache behavior ('Cached 1h at the KV level keyed on all knobs'), and diagnostics for understanding empty segments. Annotations only state read-only/idempotent, so this description carries the transparency burden and exceeds it.

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

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

The description is dense but well-organized with clear sections (model families, knobs, response top-level, caching). Every sentence adds substantial information; there is no filler. Slightly long, but the complexity of the tool justifies it. Good use of caps to highlight key terms.

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

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

With no output schema, the description fully explains the response envelope: top-level by_segment with all three segments, fed_candidates/fed_note, and _diagnostics with funnel counters. It also explains why segments can be empty and how diagnostics help. This is complete for an agent to invoke and interpret the result without external documentation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning for min_partition_leg_kelly (explains why min_kelly doesn't apply to parent-level basket trades), describes the tradeable-edge knobs as a group, and clarifies that edge is net of slippage. This goes beyond the schema descriptions.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly differentiates from siblings like polymarket_arbitrage and polymarket_edge_tracker by emphasizing the Pipeworx disagreement angle and the 'what should I bet on today' use case.

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

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

Provides strong context for when to use: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' Also explains tradeable-edge knobs with explicit example settings (e.g., 'Set to 5000 to drop thin-book opportunities'). Does not name alternatives explicitly, but the context is clear enough to distinguish from siblings.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral detail: 60-day snapshot TTL, snapshots written only on cache-miss (gaps mean no scan), decay computed from daily closes not intraday, and edge values signed by trade direction. This goes well beyond the annotation coverage.

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

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

The description is well-structured with clear sections (Args, RESPONSE, LIMITS) and front-loads the core purpose. Although long, every sentence contributes essential detail about response semantics or limitations; there is no filler.

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

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

With no output schema, the description must explain return values, and it does thoroughly: tracked[], expired[], and snapshot_dates[] are all defined with their semantics. It also covers data availability constraints (TTL, cache-miss behavior) and computation methodology, making it complete for a complex telemetry tool.

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

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

The input schema already documents both parameters fully (100% coverage), including defaults and clamps. The description reiterates defaults ('days (lookback, default 14, max 30)', 'window ... default "1wk"') but adds no semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a highly specific purpose: 'Edge persistence and decay telemetry' that answers 'how long has this edge existed and is it shrinking?'. It clearly distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence rather than current edge values.

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

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

The description gives clear context for when this tool is relevant—assessing whether an edge is fresh versus old ('a fresh wide edge and a 3-week-old wide edge are different trades'). However, it does not explicitly name alternatives or state when not to use it, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral detail: walks the ladder, returns verdicts (clean/degraded/cannot_fill), lists per-leg fill detail, thin legs, and forced directional risk. No contradiction with annotations.

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

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

The description is long but every sentence adds critical information. It is front-loaded with purpose, then uses clear caps like REQUIRES, SINGLE-MARKET, BASKET, and USE THIS to structure instructions. 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?

With no output schema, the description thoroughly enumerates return values in both modes (top_of_book, vwap_fill_price, capture_ratio, thin_legs, etc.). It also covers edge cases like partial fills and forced directional risk, making it complete for a complex dual-mode tool.

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

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

Schema description coverage is 100%, but the description enriches parameter meaning: explains side options per mode, size_usd interpretation (max spend vs target proceeds vs settlement notional), default values, and clamping (10-1,000,000). This goes well beyond the schema's basic 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 opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market vs basket) and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk and slippage.

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

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

Explicit guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable on thin books, partial fills cause unhedged risk), giving clear when-to-use context.

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

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

The description goes well beyond the annotations by detailing safety fields, warning conditions, matching logic, temporal alignment, and skipped-pair counters. It also cautions that most pre-mapped topics currently return warnings, which is valuable behavioral context. No contradiction with annotations.

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

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

The description is long but every sentence earns its place, with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and a front-loaded main purpose. The density is justified by the tool's complexity and reduces ambiguity for an AI agent.

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

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

Given no output schema, the description compensates by specifying the response structure, spread direction (Kalshi − Polymarket), safety fields, and temporal alignment. It covers prerequisites, limitations, and interpretations, making it complete for an agent to invoke and interpret correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the dual-mode behavior, enumerating all topic values, and clarifying that explicit ticker/slug override the topic-mapped sides. This elevates it to a 4.

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

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

The description opens with a precise statement of the tool's purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparison and equivalent bet shapes.

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

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

It provides clear invocation modes (topic shortcuts vs. explicit ticker/slug) and explains when the tool returns compatibility_warning, effectively excluding non-equivalent or unrelated events. However, it doesn't explicitly name alternative sibling tools or state 'use X instead', which keeps it from 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 state readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the return format ('attribute rows and geometry') and the sampling behavior, which goes beyond the structured annotations.

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

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

The description is two tight sentences. It front-loads the core action, lists key parameters compactly, and closes with a useful tip. Every word earns its place, and it is perfectly sized for the tool's complexity.

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

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

Even without an output schema, the description covers the tool's purpose, parameter semantics, return type (rows + geometry), and provides a usage example. It also names the prerequisite (search_datasets), making it sufficiently complete for an agent to select and invoke the tool correctly.

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

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

The schema covers 100% of parameters, so the baseline is 3. The description adds semantic value by explaining 'SQL-like where' and providing a sampling usage example, which gives practical meaning beyond the raw schema descriptions.

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

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

The description clearly states 'Query an ArcGIS Feature Service / Map Service layer by its url', combining a specific verb ('Query') with a precise resource (ArcGIS layer). It also lists key parameters and mentions the url comes from search_datasets, which distinguishes it from sibling tools like layer_info or search_within.

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

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

The description gives clear context: the url should come from search_datasets, and it provides a practical tip ('Use where="1=1" + out_fields="*" to sample'). However, it does not explicitly mention alternatives or when not to use this tool, such as when metadata is needed (layer_info).

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 valuable context beyond annotations: scoping to the user's identifier (IP, key hash, or account ID) and the list-all behavior when key is omitted. No contradiction with annotations.

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

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

Three sentences deliver the core action, usage examples, scoping, and sibling references without any filler. Every sentence contributes new information.

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

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

For a simple 1-parameter read-only tool without an output schema, the description covers purpose, usage, scoping, and related tools. 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% — the key property already documents 'Memory key to retrieve (omit to list all keys)'. The description reiterates this behavior but adds no new syntactic detail, so it meets the baseline for fully-schema-documented parameters.

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

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

The description clearly states the tool's function: retrieve a value saved via remember or list all saved keys when omitted. It explicitly references sibling tools (remember, forget), distinguishing this as the retrieval 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?

It provides explicit usage context: 'Use to look up context the agent stored earlier' and contrasts with re-deriving from scratch. It also names companion tools ('Pair with remember to save, forget to delete'), giving alternatives and related operations.

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

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

The description discloses important behavioral traits such as mark_read persistently flagging events and poll-friendliness. However, it directly contradicts the annotations: readOnlyHint=true claims no environment modification, while mark_read:true changes persisted read state so future calls exclude those events. This annotation contradiction forces a score of 1 per rubric.

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?

Five sentences, front-loaded with the core purpose, and every sentence adds value. It covers return fields, filtering, mark_read semantics, polling, and an alternative access method without redundancy or filler.

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

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

For a tool with 5 optional parameters and no output schema, the description is highly complete: it describes what is returned (source, citation_uri, raw payload), filtering options, mark_read behavior, and polling suitability. The only issue is the annotation contradiction, which is handled separately.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful semantics beyond the schema: it clarifies that mark_read affects subsequent calls, ties 'since' to fired_at, and gives a concrete type example. This elevates it above baseline.

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

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

The description clearly states the tool's purpose with a specific verb ('Pull fired events') and names the resource ('subscription feed'). It distinguishes itself from siblings by focusing on evaluator-written alerts with source, citation_uri, and raw payload, which is not covered by list_subscriptions or 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?

The description provides clear usage context: retrieving recent alerts, filtering by type/since, using mark_read, and polling. It also mentions an alternative endpoint for scripts/dashboards. However, it does not explicitly contrast with sibling tools like list_subscriptions or recent_changes, so it lacks a full when-not-to-use guide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description goes beyond this by detailing fallback behavior (GDELT→GNews fallback, USPTO soft-fail due to API sunset), the 'ONE parallel call' fan-out approach, and the format of the `since` parameter. This is valuable operational context not captured in annotations.

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

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

The description is dense but every sentence earns its place: examples, source details, parameter semantics, return structure, and alternative tool guidance. It is front-loaded with intuitive example queries and maintains a clear structure, making it easy for an agent to parse quickly.

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

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

For a tool with no output schema, the description sufficiently explains the return format (structured changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It also covers edge cases like the USPTO API sunset and rate-limit fallback, making the behavior fully predictable. The alternative tool reference rounds out the context.

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

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

Schema coverage is 100%, so parameters are fully documented. The description adds practical guidance by specifying accepted date formats (ISO or '7d', '30d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring, which goes beyond the schema's static 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 defines the tool as a 'change feed for a company in the last N days/weeks/months' with a specific verb and resource. It lists concrete sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes itself from the sibling tool entity_profile, which retrieves static profiles.

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

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

The description opens with natural-language query examples ('What's new with X', 'latest on Y') establishing exactly when to use it. It explicitly states an alternative: 'Use entity_profile instead when you want the static profile... regardless of window', providing clear contrast between the two tools.

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

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

Annotations already declare idempotentHint true and destructiveHint false. The description adds valuable context beyond this: key-value scoping by identifier, persistent for authenticated users, and 24-hour retention for anonymous sessions. This goes beyond the annotations but could still disclose more (e.g., overwrite behavior or size limits), so not a perfect 5.

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 core purpose, followed by usage examples, storage semantics, and sibling tools. Every sentence earns its place without redundancy or filler. The structure is logical and scannable.

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

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

For a simple two-parameter tool with no output schema, the description fully covers what the tool does, when to use it, persistence rules, and related tools. It is self-contained and leaves no critical gaps for an agent to successfully invoke it.

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

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

The schema already provides 100% coverage with descriptive fields for key and value. The description adds meaningful examples of what to store (resolved ticker, target address, user preference) and explains the key-value pairing concept, enriching the schema's bare parameter descriptions. Baseline is 3, and the added context justifies a 4.

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

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

The description uses a specific verb ('Save data') and resource ('data the agent will need to reuse later'), clearly differentiating from sibling tools by explicitly naming recall and forget for retrieval and deletion. It also explains the key-value storage model, leaving no ambiguity about what the tool does.

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

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

Provides explicit guidance on when to use: 'Use when you discover something worth carrying forward' with concrete examples (ticker, address, preference). It also names alternatives ('Pair with recall to retrieve later, forget to delete') and clarifies persistence differences for authenticated vs. anonymous sessions, covering both usage and exclusions.

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

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

With annotations already marking the tool as read-only and non-destructive, the description adds useful behavioral context: it 'cascades through several lookup endpoints internally' and returns specific fields like ticker, CIK, RxCUI, and citation URIs. This goes beyond the schema and annotations, though it doesn't mention potential errors, rate limits, or latency.

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

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

The description is somewhat long but well-structured, starting with example queries and a clear directive, then organizing supported types into a compact section. It is efficient and avoids fluff, though it could be slightly more concise by trimming redundant phrasing.

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

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

Even without an output schema, the description thoroughly explains what the tool returns for each entity type, including specific identifiers and citation URIs. It also clarifies input formats and the internal cascade behavior. This makes it complete for an agent to understand the tool's behavior and expectations.

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

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

The schema already provides 100% parameter description coverage. The description adds a few extra details, such as 'auto-disambiguated' for company names and examples of accepted values for both types. This is a modest improvement over the schema, so a 4 is appropriate rather than a 5.

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

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

The description clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It provides concrete example queries ('What's the ticker for…', 'find the CIK for…') and outlines supported entity types (company, drug). This distinguishes it from sibling tools by framing it as the entry point for identifier lookups.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' which gives a clear when-to-use directive. It also explains that it replaces 2-3 manual lookups, providing context on efficiency. However, it does not explicitly state when not to use it or name alternative tools, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds behavioral value by explaining that it probes each entity with ai_visibility_check, ranks by score, and returns specific fields (score, confidence, signal density per entity). It also surfaces the narrative of 'most/least recognized,' which goes beyond the annotations.

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

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

The description is three sentences, front-loaded with the core purpose, followed by the mechanism and use case. Every sentence earns its place: the first defines the action, the second explains the process and provides context, the third describes the output. 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?

With no output schema, the description compensates by clearly stating the return format ('ranked list with score, confidence, signal density per entity'). It also covers the use case and the relationship to ai_visibility_check. While it could mention limitations (e.g., max entities, model dependencies), the provided context is sufficient for a moderately complex tool with full schema coverage and annotations.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters. The description does not add new parameter semantics beyond what the schema provides; it only references 'entities' and 'your brand + N competitors' in general terms. Baseline 3 is correct because the schema carries the weight, and the description doesn't compensate for any gaps (there are none).

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare), the resource (AI visibility across entities), and the scope (multiple entities). It also differentiates from sibling tools by explicitly mentioning it probes via ai_visibility_check and ranks results, distinguishing it from a single-entity check.

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

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

The description provides clear context for when to use the tool: 'Useful for competitive AI-marketing audits' and gives a concrete example question. However, it does not explicitly state when not to use it or name alternatives (e.g., compare_entities). The context is clear but lacks explicit exclusions, so a 4 is appropriate.

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

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

Despite annotations already declaring readOnlyHint and idempotentHint, the description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will report timeouts. This informs the agent about latency and failure modes beyond the annotation metadata.

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

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

The description is a single, dense paragraph that efficiently lists the fan-out services, example queries, output contents, and ecosystem limitations. While longer than the shortest possible, every sentence earns its place by adding operational detail (latency, partial failures, output fields). Not overlong for the tool's complexity.

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

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

The tool is composite with no output schema, yet the description fully specifies what is returned: a summary block with field names, per-advisory detail, links, and alternative versions. It also covers limitations (NPM only) and failure behavior. This gives an agent everything needed to understand the tool's capabilities and results without additional schema.

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

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

Schema coverage is 100%, so the description does not need to compensate for undocumented parameters. The description adds no new meaning beyond the schema: it mentions 'recent alternative versions' and 'version history' but does not elaborate on the 'package' or 'version' parameters beyond what the schema already states (e.g., scoped packages, default to latest). 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 purpose: 'Composite "should I add this npm package to my project" check in ONE call'. It names the exact resource (npm package) and distinguishes itself from siblings by listing concrete outputs and ecosystem scope (NPM only in v1). This goes beyond a tautology or generic verb.

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

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

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

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral detail beyond this: it specifies the return fields (name, summary, record_count, owner/org, Feature Service url) and the open-data nature. No contradiction with annotations.

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

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

Two sentences, front-loaded with purpose, and no redundant or filler content. The first sentence states the action and scope; the second sentence concisely lists return fields and the downstream workflow. Every word earns its place.

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

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

For a tool with 3 optional parameters, full schema coverage, and strong annotations, the description is complete: it explains what the tool does, what it returns, and how the output integrates with sibling tools. No output schema exists, but the description explicitly lists the return fields, so the agent is well-equipped.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no parameter-specific details beyond what the schema already provides (query, limit, org_id) — it does not introduce new syntax or format nuances. It only reiterates 'keyword' which is already in the schema examples.

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

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

The description clearly identifies the verb ('Search'), the resource ('City of Asheville GIS open geospatial datasets'), and the scope (parcels, zoning, public works & city services). It also distinguishes itself from siblings by explicitly linking to query_layer and layer_info via the Feature Service 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 provides clear context: use this to find datasets by keyword, then pass the returned url to query_layer or layer_info. However, it does not explicitly mention alternative search tools (e.g., search_within, discover_tools) or state when not to use this tool, so it stops short of full exclusion guidance.

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

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

Even with annotations providing read-only and idempotent hints, the description adds substantial behavioral context: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K char cap with truncation flagging, and the utility of character offsets for verifying quotes. This goes far 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 two dense sentences, each earning its place: it covers the mechanism, use case, output, benefit, pairing, and technical constraints. No fluff or repetition.

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

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

With no output schema, the description adequately explains return values (top-N passages, offsets, similarity scores) and covers the character limit, truncation behavior, and embedding method. For a tool with this complexity, it is remarkably complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by giving concrete examples for text (SEC 10-K body, article) and query (supply-chain risk, fiscal year 2024 revenue), contextualizing how the parameters are intended to be used. However, it does not add substantial new information beyond the schema.

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

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

The description clearly states the tool's function: 'Semantic search INSIDE a fetched record' with explicit inputs (text + query) and outputs (top-N passages with offsets and similarity scores). It distinguishes itself from siblings by emphasizing the 'inside a fetched record' scope and explicitly pairing with ask_pipeworx_grounded.

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

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

The description gives explicit guidance: 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded, saying to 'ground over the relevant passages instead of the whole document.' This clearly communicates when to use it and how it complements an alternative tool.

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

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

The description goes beyond annotations by disclosing delivery limitations (SMS 10/day cap, phone verification), webhook failure auto-disable, and the one-time webhook signing secret. It also names the return value (subscription ID). This transparency is valuable given the tool writes data.

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, using enumeration and examples to cover a complex tool. Every major section (type, params, delivery) is addressed without redundancy, and the most important info (action, return, requirement) 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?

While the description thoroughly covers three subscription types and all delivery options, it entirely omits two of the five types defined in the schema (patent_grant, clinical_trial). This means an agent relying on the description would have an incomplete picture of the tool's capabilities, although the schema fills part of the gap.

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

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

The schema already provides 100% parameter coverage, and the description enriches this with concrete examples for sec_8k, polymarket_edge, and fred_series, plus detailed delivery channel semantics. However, it omits the patent_grant and clinical_trial types described in the schema, so not all parameter semantics are elaborated.

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

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

The description clearly states that the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes this from sibling tools like list_subscriptions and recent_alerts by focusing on creation, and enumerates concrete subscription types.

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

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

It specifies the requirement of a Pipeworx OAuth account and notes that anonymous/BYO cannot persist subscriptions, setting a clear prerequisite. It also references recent_alerts as the mechanism to pull from the always-on feed, implying the workflow of subscribe-then-pull. However, it does not explicitly compare with alternative tools for edge cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context: the output structure (category-bucketed example questions), the effect of the optional 'topic' parameter (focus vs. full spread), and that results are drawn from a live catalog of thousands of tools. 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 longer than average but every sentence earns its place: example queries, purpose, output structure, parameter usage, and when-to-use guidance. It is front-loaded with examples and clear action verbs. It could be slightly condensed, but the length is justified by the tool's onboarding role.

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

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

There is no output schema, so the description carries the burden of explaining return values—it does so by describing the category-bucketed questions and the exact tool+argument shape. It covers invocation modes (no args vs. with topic), use case, and relationship to meta-tools. Combined with strong annotations, this is complete for a read-only, idempotent 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%, so the baseline is 3. The description adds examples of topic values ('finance', 'pharma', 'betting') and says 'to focus', but the schema already explains the same behavior with the full list of values and the instruction 'Omit for a cross-category spread'. The description does not add meaningful new parameter semantics beyond the schema.

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

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

The description clearly states the tool's purpose: it's the 'onboarding entry point' that returns category-bucketed example questions with the exact tool and argument shape. It uses specific verbs like 'returns' and 'lists' and distinguishes itself from siblings by positioning itself as the first thing to use when unsure what Pipeworx can do.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also names specific alternative tools (ask_pipeworx, entity_profile, compare_entities), providing clear when-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?

The description adds behavior beyond annotations: ownership enforcement, deactivation rather than deletion, and preservation of historical events. These details are consistent with the annotations (destructiveHint=false, idempotentHint=true) and are valuable for an agent invoking the tool.

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

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

Two sentences with the primary purpose front-loaded and no filler. Every clause adds value: 'by id', ownership enforcement, and the deactivation behavior. Extremely concise and well structured.

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

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

For a single-parameter tool with rich annotations and a clear schema, the description covers the essential behavioral details: what it does, who can call it, and what side effect it has on the data. The lack of an output schema is acceptable given the simple operation and the explicit mention of preserving history via recent_alerts.

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 fully documents the 'id' parameter (string, required, description: 'Subscription id (uuid) returned by subscribe'). The description adds the ownership context ('your own subscriptions') but does not introduce new syntax or format details beyond the schema, so the 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 'Cancel a subscription by id,' which is a specific verb+resource combination that clearly distinguishes it from siblings like subscribe and list_subscriptions. It also clarifies it's for alerts via the title and the deactivation semantics.

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 it (to cancel a subscription) and important constraints (ownership enforced, only your own subscriptions). It alludes to the relationship with recent_alerts for historical events, but does not explicitly name alternatives or speak to when not to use it, so a 4 rather than 5.

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

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

Annotations already provide read-only, open-world, idempotent, and non-destructive hints. The description goes beyond these by disclosing what the tool returns (verdict types, actual value with citation, reasoning), how it computes results (exact percent-delta math, verbatim evidence), and that it replaces 4–6 sequential calls. This rich behavioral detail is not evident from annotations alone.

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

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

The description is moderately long but every sentence provides value: trigger phrases, use cases, routing logic, output structure, and efficiency gains. It is front-loaded with the core purpose and structured with a dash-separated list of return values. 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?

Given only two parameters and no output schema, the description adequately covers what the tool does, how it routes claims, what results are returned (verdict, actual value, citation, reasoning), and provides examples. It is complete enough for an agent to invoke the tool correctly without needing extra documentation.

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

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

The input schema already documents both parameters with examples, providing 100% coverage. The description adds practical nuance beyond the schema, such as recommending tolerance_pct 1–2 for hallucination detection and noting the default cap at 5. This enhances understanding of when and how to set the parameter, but the schema already carries most semantic weight.

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: natural-language claim verification against authoritative sources. It provides multiple trigger phrases ('fact check', 'verify the claim that…') and concrete examples, distinguishing it from sibling tools like ask_pipeworx or deep_research by focusing on factual validation. The verb 'validate' plus 'claim' resource is specific and 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?

Explicit when-to-use guidance is given: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes the internal routing logic (SEC EDGAR for company-financial claims, grounded pipeline otherwise). However, it does not explicitly name alternative tools or describe when not to use this tool, so it stops short of the top score.

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