Arcgis Chapelhill

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the bar is lower. The description adds useful context beyond annotations: the default free model, the BYO-key cost implication ('you pay Anthropic directly'), and the per-model response shape. It does not cover rate limits or failure behavior, but the added cost and model selection details are meaningful.

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

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

The description is three sentences, each earning its place: purpose, model/cost caveat, return format, and use cases. It is front-loaded with the core function and contains no filler or repetition of schema details.

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

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

Given there is no output schema, the description compensates by listing the return fields (score, confidence, signals, raw_response) plus a combined view. It covers parameter behavior, default behavior, cost, and usage scenarios. Minor gaps like what 'signals' means or error handling prevent a 5, but it is reasonably complete for read-only, non-destructive use.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description deepens parameter understanding by explaining that `_apiKey` is passed straight through to api.anthropic.com with direct billing, and that omitting `models` yields just the free Workers AI default. This adds practical value beyond the schema's field-level 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: 'Probe one or more LLMs for what they know... and score visibility (0-100) per model.' This distinguishes it clearly from siblings like ask_pipeworx, deep_research, or compare_entities, which are either domain-specific or broader research tools. The scope (business/brand/product/topic) is explicit.

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

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

The description provides clear use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the default model and when to supply an Anthropic key. However, it does not explicitly name alternatives or state when not to use this tool, 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 cover read-only, open-world, idempotent, non-destructive. The description adds useful context: routes to multiple tools, returns structured answer with stable citation URIs, works on every tier, and one fast call. No contradiction with annotations.

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

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

The description is front-loaded with 'PREFER OVER WEB SEARCH' and structured with 'START HERE' and 'Step up only when needed'. It is somewhat long but every sentence adds actionable guidance—examples, triggers, and alternatives.

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

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

The description covers scope, sources, return behavior (citation URIs), default status, and escalation paths. With annotations covering safety and schema covering parameters, this is highly complete for a complex routing tool.

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

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

The schema fully documents all parameters (question and five aliases) with 100% coverage. The description only provides example questions, adding no new param semantics beyond what the schema already states.

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

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

The description clearly states this tool answers factual questions by routing to 5,529 tools and returns structured answers with citation URIs. It distinguishes itself from siblings by name (ask_pipeworx_grounded, deep_research) and by positioning itself as the default entry point.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and gives concrete triggers ('what is', 'look up', 'find'), plus examples. It names specific alternatives for when to step up (ask_pipeworx_grounded, deep_research) and explains when each is appropriate.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the experimental nature, the fact that no candidate is currently active, and that it is a full working router with no fallback. This adds meaningful behavioral 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 compact but information-dense, covering purpose, current state, usage guidance, and caveats in a few sentences. It is front-loaded with the key identity as a beta version. Minor redundancy with the schema is present but not harmful.

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 (universal router with 5,529 tools) and lack of output schema, the description is remarkably complete: it explains what it is, how it relates to ask_pipeworx, its current parity, its experimental purpose, and its full functionality. No critical information 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?

The schema already covers all six parameters with 100% coverage, including aliases and their purpose. The description does not add parameter-specific detail, but none is needed given the schema's completeness. Baseline 3 is appropriate.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router with identical tools and response shape. It explicitly differentiates from the stable sibling ask_pipeworx by its experimental routing improvements, making its purpose unambiguous.

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

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

It explicitly states to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains the comparison process against the stable router. This gives clear when-to-use context and indirectly contrasts with the stable version.

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?

Description goes beyond readOnlyHint by disclosing the refusal mechanism (five explicit refusal reasons), the evidence requirement (verbatim quote), and the extra LLM call cost. It also guarantees no invention ('using ONLY what the tool result contains'), which aligns with annotations and adds trustworthy behavioral info.

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

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

Each sentence provides distinct information—definition, routing, extraction, return structure, use case, cost—without redundancy. The structure is front-loaded with the core value proposition and flows logically.

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 complex, and the description covers mechanism, output/refusal shapes despite no output schema, and operational trade-offs. An agent has all needed context to select and invoke correctly.

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

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

Schema already documents all six parameters as aliases of 'question' with 100% coverage; the description does not add parameter-level details. Baseline 3 applies because the schema carries the parameter semantics.

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

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

Clearly identifies itself as a hallucination-resistant answer mode with explicit contrast to ask_pipeworx via 'Same routing as ask_pipeworx' plus 'EXTRACTS the answer using ONLY what the tool result contains'. Names the specific verb+resource (answer extraction with evidence) and distinguishes from siblings.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts'. Also provides exclusion: 'prefer ask_pipeworx for casual lookups' and names the sibling alternative. This is exactly the when/when-not guidance needed.

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

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

The description goes far beyond the minimal annotations by revealing detailed behavior: parallel fan-out to category-specific data packs, resolver contract with match confidence and alternatives, safety short-circuiting of low-confidence matches, illiquid-wide-spread handling, news fallback fields, and resolution-rule risk parsing. No annotation contradiction exists; readOnlyHint and idempotentHint are consistent with a research-only tool.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY) and front-loaded purpose/use cases. Every section carries operational information, though some repetitive fan-out examples could be condensed without losing critical guidance.

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

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

Given the complexity and absence of an output schema, the description is exceptionally complete. It documents the response shapes (result.market, result.analysis, result.evidence), resolver contract fields, parent_event extraction, news fallback fields, blocking statuses, and cancellation-rule risk. This gives an agent everything needed to correctly invoke the tool and interpret results.

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 all three parameters with 100% coverage, including market formats, depth enum, and include_raw behavior. The description adds nothing substantially new about parameters—it only repeats the market input formats already in the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The first sentence states exactly what the tool does: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also specifies the accepted input formats (slug, URL, or question text) and explicitly lists use-case queries ('should I bet on X', 'is there edge in Z'), which distinguishes it from sibling edge/arbitrage tools by focusing on evidence gathering and market-vs-model comparison.

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

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

The description provides explicit 'Use for' guidance and covers important routing conditions: low-confidence matches are blocking, closed/dead markets return a specific status, and wide-spread markets are flagged. However, it does not name alternatives or explicitly state when to use another sibling tool (e.g., polymarket_edges), so it lacks full exclusionary guidance.

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

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

Beyond the read-only, open-world, idempotent annotations, the description discloses data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), sorting by primary metric, handling of off-calendar fiscal years, and return format with citation URIs. This adds substantial behavioral context 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 dense but efficiently organized: it opens with usage triggers, states the core action and scope, then details type-specific data sources, sorting, and return format, ending with an efficiency note. Every sentence earns its place; 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?

Despite having no output schema, the description fully covers return format (paired data + pipeworx:// URIs), sorting behavior, data sources, and the efficiency benefit over sequential lookups. It provides all necessary context for an agent to select and invoke this 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?

Though the schema documents both parameters (type and values) with 100% coverage, the description enriches this by explaining what each type pulls (10-K financials vs adverse-event counts), providing value examples, and clarifying the 2–5 entity limit. This goes far beyond the schema's basic enum and array 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 a side-by-side comparison tool for 2–5 entities, with specific verbs like 'compare' and 'rank'. It distinguishes itself from sequential lookups and sibling tools like entity_profile by explicitly stating 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'.

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

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

Explicitly lists trigger phrases such as 'Compare X and Y', 'X vs Y', 'which is bigger', and 'rank these companies', and states when to prefer this tool over alternatives. It also gives concrete examples for both company and drug types, making the appropriate use case unmistakable.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses account/payment requirements, parallel tool routing, return packet contents (evidence, confidence, source, fetched_at, citation), gaps[] that never invent, fetchable citation_uri, contradictions[] for standard/thorough, and latency ranges. No contradictions with annotations.

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

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

The description is long (~300 words) but every sentence adds value—account requirements, usage scope, comparison to sibling tools, return format, latency—and it is front-loaded with the most decision-relevant constraints. While it could be trimmed, the density of information justifies its length.

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

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

For a tool with no output schema, the description fully explains return values (findings packet, gaps[], contradictions, hop field, citation_uri), prerequisites, latency, and alternative tools for out-of-scope cases. It is exceptionally complete given the tool's complexity.

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

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

The input schema already describes both parameters in full (100% coverage), including the depth enum's meaning. The description does not add new parameter-level semantics beyond what the schema states, so it stays at baseline 3.

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

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

The description opens with a clear verb+resource definition: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources.' It differentiates from open-web search and from ask_pipeworx, making the tool's niche unmistakable.

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

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

Explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and alternatives for single lookups and breaking news. Also warns about account requirements and directs non-signed-in users to ask_pipeworx.

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

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

Annotations already indicate readOnly, idempotent, non-destructive behavior. The description adds valuable behavioral context: results are 'ready to call directly, no second schema lookup needed' and includes full input schemas with examples. This goes beyond the safety profile 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?

Although lengthy, every sentence serves a purpose: purpose, usage, return format, and strategic advice. The domain list is informative, and the structure front-loads the primary verb and resource before elaborating. No wasted words.

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

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

The tool has a straightforward query+limit interface, high schema coverage, and annotations. The description rounds out the picture by specifying the return payload (top-N, full schemas, examples) and the 'no second lookup' guarantee, making it fully adequate for an agent to decide when and how to use it.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds semantics by giving a broad list of acceptable query topics (SEC filings, FDA drugs, etc.) and clarifying that the query is a 'natural language description of what you want to do', which helps the agent formulate effective queries.

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 finds tools by describing data or task, with a specific verb ('Find') and resource ('tools'). It enumerates many example domains and explicitly describes the return value (top-N tools with schemas), distinguishing it from siblings like query_layer or search_datasets.

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

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

The description provides strong usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. It implies a contrast with getting 'just one answer', but does not explicitly name alternative tools or provide when-not-to-use conditions, 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 indicate read-only, non-destructive, idempotent behavior, and the description adds substantial context: parallel fan-out across SEC EDGAR, XBRL, USPTO, news, and GLEIF; fallback behavior (GDELT→GNews); and a soft-fail note for the patents API sunset. 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 dense and front-loaded with purpose and usage, which is good, but it is a long single paragraph with multiple example triggers. Given the absence of an output schema, the length is justified by the need to document return fields and caveats, but a bit more formatting (bullets) would improve scannability.

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

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

Despite no output schema, the description lists all major return fields (cik, filings, fundamentals, patents, news, LEI), input limitations, fallback mechanisms, and API sunset behavior. This provides an agent with enough context to use the tool correctly and know what to expect, and no major gaps are obvious.

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

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

The input schema already provides full descriptions for both parameters (type enum and value with ticker/CIK examples). The description repeats these examples ('AAPL', '0000320193') and the name limitation, but adds no genuinely new parameter semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly defines the tool's purpose with specific verbs ('profile', 'brief me on') and the resource ('US public company'), and the phrase 'full cross-source profile' distinguishes it from single-source lookups. It also explains the output components and input constraints, making the purpose unmistakable.

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

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

Explicit when-to-use guidance is given via example queries ('Tell me about X', 'brief me on Tesla') and the directive 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states a clear alternative: 'use resolve_entity first if you only have a name.'

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 and idempotentHint, so the description does not need to repeat those. It adds context about deleting previously stored memory and sensitivity, but does not disclose additional behavioral traits beyond 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 concise sentences: purpose, usage scenarios, and related tools. No redundancy or fluff; every sentence adds value.

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

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

Given the simplicity of the tool (one parameter, clear annotations, no output schema), the description fully covers purpose, when to use, and complementary tools. No gaps.

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

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

Schema description coverage is 100%, with the parameter 'key' already described as 'Memory key to delete'. The description adds no further semantics beyond confirming deletion by key, so baseline 3 is appropriate.

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

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

The description clearly states the tool deletes a previously stored memory by key. It distinguishes itself from sibling tools like remember and recall by specifying the delete action and the resource (memory).

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

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

Explicitly provides when to use: when context is stale, task is done, or clearing sensitive data. Also suggests pairing with remember and recall, giving complementary tool guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds valuable behavioral context by stating it 'fetches the page' (an external network call) and emits a 'standard llms.txt markdown format' output. This goes beyond the generic safe-read annotations, warranting a score above baseline.

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

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

The description is concise and well-structured: two sentences covering functionality and output, followed by a clear 'Useful for' list. Every sentence earns its place without repetition or fluff.

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

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

Despite having no output schema, the description explicitly states the output format ('single text blob ready to drop at site-root/llms.txt') and the process (fetch, extract, emit). It covers the tool's behavior, use cases, and output, making it complete for its moderate complexity.

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

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

Schema description coverage is 100%, so the parameters are already well-documented. The description adds minimal semantic value beyond the schema, mentioning 'any URL' and 'key links' but not introducing new parameter-related detail, which aligns with the baseline of 3.

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

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

The description clearly states the tool's purpose with a specific verb ('generate'), resource ('llms.txt file'), and outcome ('so AI crawlers can index the site cleanly'). It also distinguishes the tool from siblings by focusing on llms.txt generation, a unique niche among the listed sibling tools.

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

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

The description provides explicit 'Useful for' scenarios (client indexing, personal drafts, competitor auditing), which gives clear context on when to use the tool. However, it does not mention when not to use it or explicitly name alternatives like scan_competitor_ai_presence, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds behavioral context by specifying exactly what information is returned (fields, geometry type, record count, capabilities), which goes beyond the annotations and helps the agent anticipate the tool's output.

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

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

The description is a single, well-structured sentence that front-loads the action and resource, then concisely lists the output fields. Every word earns its place, with no redundancy or filler.

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

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

Given the tool's simplicity (one parameter, full schema coverage, no output schema), the description fully covers what the tool does and what it returns. It is complete for an agent to select and invoke correctly without needing additional context about prerequisites or error handling.

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 defines the single 'url' parameter with a clear example and description, achieving 100% schema description coverage. The tool description adds no additional meaning beyond the parameter's name and purpose, so it meets the baseline but does not 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 with an action verb ('Get') and a specific resource ('an ArcGIS Feature/Map Service layer's schema by url'). It enumerates the exact outputs (fields, geometry type, record count, capabilities), which distinguishes it from sibling tools like query_layer that retrieve data rather than schema.

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

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

The description provides clear context that this tool is for schema/metadata retrieval, not for querying features. It does not explicitly name alternatives or exclusions, but the focus on schema makes the intended use obvious compared to sibling tools like query_layer or search_within.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint). The description adds a useful list of return fields and reinforces that only active subscriptions are listed by default, but it does not disclose potential behavioral details like pagination or rate limits. With annotations present, this meets the baseline but doesn't exceed 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 two sentences, front-loaded with the core verb and resource. The first sentence states the purpose, the second lists return fields and usage scenarios. Every sentence contributes value with no redundancy or wasted words.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers the return fields (id, type, params, timestamps, fire_count) and the intended use cases (review monitoring, find id to cancel). This is complete enough 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 single optional parameter include_inactive is fully described in the schema with its default value, giving 100% schema coverage. The description doesn't add additional parameter semantics, but it doesn't need to since the schema is sufficient. The mention of 'active subscriptions' aligns with the parameter's purpose.

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' and clearly identifies the resource as 'the caller's active subscriptions,' which distinguishes it from sibling tools like subscribe and unsubscribe. It also specifies the scope (caller's own subscriptions) and the return fields, making the purpose unambiguous.

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

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

The description explicitly states when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel.' This gives clear context, but it does not explicitly name alternative tools or state when not to use it, so it lacks the full 'when-not' guidance.

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

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

Annotations are all false and provide no safety hints, so the description carries the full burden. It goes beyond by disclosing rate limits ('5 per identifier per day'), the claim_token mechanism for follow-ups, that it's free and doesn't count against quota, that the team reads digests daily, and that signal affects roadmap. This is rich behavioral context that helps the agent manage expectations.

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

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

The description is long but avoids fluff. It starts with the core purpose, then usage conditions, exclusions, feedback etiquette, token behavior, and service details. Every sentence provides actionable information, but the density of procedural details could be better chunked or bulleted for faster scanning. Still, 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?

The tool has no output schema, but the description explains the return behavior (claim_token for anonymous filing, reading status later). It covers what qualifies as feedback, requires tool-specific context, explains limits, and even addresses privacy (don't paste end-user prompts). Combined with the rich schema (100% coverage, nested context object), the description fully contextualizes the tool's use.

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

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

Schema descriptions already cover all parameter meanings (type enum, context object, message, claim_token), so the baseline is 3. The description adds extra semantic guidance: don't paste the end-user's prompt, describe issues in terms of Pipeworx tools/packs, and explains the claim_token round-trip flow more clearly than the schema alone. This meaningful addition 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 ('Tell') and resource ('Pipeworx team') and immediately enumerates what counts as feedback (broken, missing, needs to exist). It clearly distinguishes itself from sibling tools like ask_pipeworx and discover_tools by positioning itself as a feedback channel, not an information retrieval or analysis 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?

It explicitly states when to use the tool ('when a tool returns wrong/stale data', 'a tool you wish existed', 'worked surprisingly well') and gives a clear exclusion: do not use for tools from other MCP servers, with the alternative action 'file it with that server instead.' This is a textbook example of 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 readOnlyHint=true and non-destructive behavior. The description adds significant context beyond those hints: data provenance ('derived from CF analytics-engine'), privacy ('no PII'), the exact aggregation granularity ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). This fully informs the agent of the tool's operational traits.

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 a front-loaded purpose statement, a clear return summary, and contextual details. The 'Useful for' list adds length but each bullet provides actionable guidance, so no sentence is wasted.

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

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

Despite having no output schema, the description fully explains what the tool returns (top tools, top packs, call volume), how to choose the window, why it's useful, and its provenance/privacy/caching behavior. For a simple single-parameter read-only tool, this is exceptionally complete and self-contained.

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

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

The schema entirely covers the single `window` parameter with an enum and a description explaining trade-offs between windows. The tool description mentions the window options but adds no new semantic information beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description opens with a clear, specific statement of what the tool does: 'What other AI agents are calling on Pipeworx right now' and lists the concrete outputs (top tools, top packs, total call volume). It distinguishes itself from sibling tools like discover_tools by focusing on aggregated usage patterns rather than general tool discovery.

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

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

An explicit 'Useful for' section provides three concrete use cases, from discovering hot data sources to confirming canonical tool choice. However, it doesn't name alternative tools or state when not to use this tool, falling just short of perfect 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 goes far beyond annotations by detailing the semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slug drops, >20% placeholder returns null), fill check against live CLOB depth, and threshold 'realizable_edge_pp ≤ 0 means... do not trade it.' It also discloses skipped_low_similarity reporting. Annotations only indicate read-only/idempotent/open-world; the description adds substantial behavioral context without contradiction.

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

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

Though lengthy, the description is structured into thematic blocks (modes, semantic anchor, partition filter, response, fill check, custom sizing). Every sentence carries operational detail; there is no filler or repetition. The front-loaded purpose and mode selection allow quick orientation.

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

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

Given the tool's complexity (two modes, filters, fill check, response shape) and the absence of an output schema, the description is remarkably complete. It explains return fields, edge cases (null signals, thin legs), and references a sibling tool for related functionality. No critical gap is 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?

Schema description coverage is 100% for both params, but the description enhances each: event gets example slugs and 'full URLs also accepted,' topic gets seed question examples and cross-event semantics. It explains the difference between modes and what each parameter triggers, adding meaning beyond the schema.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three invocation modes (trending_scan, event, topic) and alludes to sibling tools like polymarket_fill_risk, making the tool's unique role evident.

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 actionable: 'Call with NO args for a trending_scan... pass event... or topic...' It recommends event for specific markets, topic for cross-event scans, and points to polymarket_fill_risk for custom sizing. This constitutes clear when-to-use and when-not-to-use direction.

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 numerous behavioral traits beyond the annotations, including a 1-hour KV cache, response segmentation (by_segment), diagnostics for empty segments, and a caveat about Fed signals being unreliable. It also explains model families and gate conditions, far exceeding the annotation hints.

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

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

The description is a dense wall of text with many parenthetical details (per-sport alpha values, prior gate values like '85%/5%/50:1') that could be moved to an output schema or examples. It is not front-loaded; while the first sentence conveys purpose, the rest is overloaded with detail, making it harder to parse efficiently.

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

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

Despite the lack of an output schema, the description thoroughly explains response top-level fields (by_segment, fed_candidates, _diagnostics) and per-opportunity fields (edge_pp_net, kelly_fraction). It also describes the model families and filter knobs, making it complete enough for an agent to understand the output, though it could benefit from concrete examples or exact nested structures.

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

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

Schema coverage is 100%, and the schema already provides detailed descriptions for each parameter (e.g., slippage_pp discusses zero fees and typical slippage). The description's mention of 'TRADEABLE-EDGE KNOBS' adds context but largely restates what the schema already covers, so it does not add much semantic 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 opens with a specific action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx disagreement and daily discovery.

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

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

The description explicitly states it's 'Built for "what should I bet on today"' and mentions agents discover opportunities without paging hundreds of markets, providing a clear use case. However, it does not explicitly contrast with sibling tools or state when not to use it.

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

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

The description adds substantial behavioral context beyond the annotations, including the 60-day snapshot TTL, snapshot behavior on cache-miss with gaps, decay computed from daily closes rather than intraday, and the signed nature of edge_pp_net (negative = SELL YES). This is far more than the readOnly/openWorld/idempotent hints already 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 well-structured with ARGS, RESPONSE, and LIMITS sections, and it front-loads the core purpose. However, it is fairly long and includes some redundancy with the schema (e.g., repeating default values), so it does not earn a perfect 5.

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

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

Without an output schema, the description fully compensates by explaining the response structure (tracked[], expired[], snapshot_dates[]) with sufficient detail, and also covers important edge cases (snapshot gaps, TTL bounds, data freshness). This makes the tool usable without needing to infer return behavior.

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 repeats the defaults and adds slight context (e.g., 'lookback', 'snapshot family'), but it does not substantially enrich the parameter meanings beyond what is already in the schema. It even omits the enum values for window that the schema includes.

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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a specific question: 'how long has this edge existed and is it shrinking?' This is a specific verb+resource+scope that distinguishes it from the sibling tool polymarket_edges, which likely shows current edges.

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

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

The description implies when to use the tool: when you need to know edge persistence and decay, and even provides a concrete use case ('the median lifespan is your competition clock'). However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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

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

Beyond the read-only/annotations, the description discloses detailed behavioral traits: it 'walks the ladder', computes VWAP fill prices, returns a clean/degraded/cannot_fill verdict, and identifies forced_directional_risk. It warns about partial basket fills and thin books, which are non-obvious but critical behaviors. No contradiction with the readOnlyHint, idempotentHint, or destructiveHint 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 it is front-loaded with the core purpose and uses uppercase mode markers (SINGLE-MARKET:, BASKET:) to structure the content. Every sentence adds operational detail with no filler. It borders on essay-length, but the dual-mode complexity justifies the density, so it earns a 4 rather than a 5.

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

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

With no output schema, the description fully enumerates return values for both modes (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, thin_legs[], etc.) and even explains error conditions like cannot_fill. It covers defaults, parameter constraints, and the risk rationale. The only minor omission is explicit rate-limit or error-handling notes, but overall it is complete for safe invocation.

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

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

Although the input schema already covers all 4 parameters, the description adds essential semantic depth: `size_usd` means max spend on buys but target proceeds on sells, and in basket mode it becomes settlement notional per share. It also explains `side` defaults (buy_yes vs auto) and the market/event mode selection, going well beyond the schema's one-line 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 'Realizable-vs-theoretical edge check against live CLOB order-book depth', a specific verb+resource phrase that precisely defines the tool's function. It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than edge discovery, and the two-mode breakdown (single-market vs basket) adds clarity.

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 before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', naming exact sibling tools and a threshold. It also explains the consequence of not using it (theoretical overround not capturable, partial fills convert arb into unhedged directional position), 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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses extensive behavioral details: compatibility_warning conditions, temporal_alignment, skipped_cross_type counters, and the meaning of matches. It even warns that 'pre-mapped ≠ tradeable.' This far exceeds what annotations alone 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 lengthy but front-loaded and structured with labeled sections like 'TWO MODES,' 'RESPONSE,' and 'SAFETY FIELDS.' Every sentence delivers unique, essential information; there is no fluff or redundancy.

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

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

With no output schema, the description compensates by explaining the response format (leg prices, spread values, top_spreads_pp) and all safety/edge-case fields. It also covers temporal alignment and skipped-comparison counters, making the tool's behavior fully understandable for a complex cross-venue comparison tool.

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

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

The schema already provides 100% coverage for all three parameters, but the description adds important interaction semantics: topic auto-fetches events, while explicit tickers override the mapped side. This clarifies the two-mode usage 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 opens with a precise, specific purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from sibling tools by focusing on cross-venue comparison and clearly explains both modes (topic shortcuts and explicit tickers).

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

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

The description gives clear context on when to use the tool (for a question that resolves on both venues) and warns that pre-mapped topics may not be tradeable. It stops short of explicitly naming alternatives from the sibling tools, so it is not a full 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds value by stating it returns attribute rows and geometry, and provides a usage tip. This goes beyond what annotations convey, though it does not detail pagination limits or error behavior, which are partly in the schema.

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

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

The description is compact, consisting of two sentences that front-load the core purpose and then summarize parameters and return behavior. Every word adds value; no filler or redundancy.

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

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

Given no output schema, the description adequately explains return values (attribute rows and geometry). It also covers the required URL origin, parameter types, and a practical sampling pattern. Combined with the complete schema and annotations, the description is fully sufficient for an agent to use this tool effectively.

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

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

Schema description coverage is 100%, providing baseline 3. The description adds semantic context by noting the where clause is SQL-like, out_fields is comma-separated, and order_by/limit/offset are supported. The sampling tip further clarifies parameter usage, adding value beyond the schema.

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

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

The description clearly states the tool queries an ArcGIS Feature Service / Map Service layer by URL, explicitly mentioning it is from search_datasets. It lists the key parameters (where, out_fields, order_by, limit, offset) and distinguishes itself from siblings by specifying the resource type and data source.

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

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

The description provides clear context by noting the URL comes from search_datasets, indicating a workflow dependency. It also gives a practical sampling tip (where="1=1" + out_fields="*"). However, it does not explicitly mention alternatives or when not to use this tool, such as layer_info for metadata or search_within for spatial queries.

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

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

The annotations already declare readOnlyHint and idempotentHint, and the description adds context about scoping ('Scoped to your identifier...') and the optional key behavior ('or list all saved keys'). It does not contradict annotations.

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

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

Three sentences, front-loaded with the core action, uses its space efficiently with examples and scope. No 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?

For a simple one-parameter, read-only tool, the description covers the purpose, usage, scope, and sibling relationships. Without an output schema, it implies the return values ('a value' or 'all saved keys') but doesn't specify exact format, which is acceptable for this tool.

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

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

The input schema provides a complete description of the 'key' parameter (100% coverage), so the baseline is 3. The description repeats this information and adds examples but doesn't introduce new parameter semantics.

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

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

The description uses specific verbs 'Retrieve' and 'list' with a clear resource ('a value previously saved via remember' and 'all saved keys'). It distinguishes itself from siblings 'remember' and 'forget' by focusing on retrieval, and provides concrete examples like 'user's target ticker'.

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 ('Use to look up context the agent stored earlier') and gives an alternative ('without re-deriving it from scratch'). It also references sibling tools ('Pair with remember to save, forget to delete') to guide tool selection.

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

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

It discloses that setting mark_read:true flags events as read and affects subsequent calls ('so the next call only shows newer ones'), adding nuance beyond the readOnlyHint annotation. It also describes the return payload composition and the alternative feed endpoint, enriching behavioral understanding.

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

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

Four sentences, front-loaded with the primary purpose, and every sentence earns its place. No fluff; includes filtering, mark_read behavior, and an alternative access method 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?

With 5 optional parameters and no output schema, the description covers what the feed contains, how filtering works, the mark_read behavior, and an alternative HTTP endpoint. It provides enough context for a caller to effectively use the tool without additional 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 the baseline is 3. The description adds practical meaning by showing an example type filter ("sec_8k"), explaining that since expects an ISO timestamp, and clarifying the side effect of mark_read—all enhancing the schema's bare definitions.

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

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

The description begins with 'Pull fired events from your subscription feed,' clearly stating the action and resource. It distinguishes itself from sibling tools like subscribe/unsubscribe and list_subscriptions by focusing on reading fired alerts rather than managing 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 gives clear context: 'Polls work fine' and points to an alternative HTTP endpoint for scripts/dashboards. It lacks explicit exclusions or comparisons to sibling tools, but the usage context is evident and 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 discloses source fan-out, fallback logic (GDELT→GNews, USPTO soft-fail), and the return structure (changes[], total_changes, citation URIs). These behaviors go beyond the readOnlyHint and idempotentHint annotations, offering actionable context about external dependencies and failure modes.

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

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

The description is long but information-dense, front-loaded with intent and examples, then covering sources, parameters, return format, and alternative tool. Every sentence contributes unique value, and the structure is logical.

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

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

Given the tool's complexity (multi-source fan-out, API fallbacks, time windows), the description covers purpose, behavior, exceptions, and output format. It also references an alternative tool, making it self-contained for an agent to decide on usage.

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 fully describes all three parameters with formats and examples. The description adds a recommendation for `since` ('Use "30d" or "1m" for typical monitoring') but little else that is not already in the schema, so the added value is marginal.

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 provides a change feed for a company over a time window, using examples like 'What's new with X' and explicitly naming the data sources. It distinguishes itself from entity_profile by contrasting dynamic changes with 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?

It provides explicit usage examples and explains the fallback behavior. Most importantly, it directly tells the agent to 'Use entity_profile instead when you want the static profile...', giving clear when-to-use vs 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?

The description adds behavioral context beyond annotations: persistence semantics are disclosed ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'), and it explains scoping by identifier and key-value storage. It does not contradict the annotations (readOnlyHint=false, idempotentHint=true), and the retention policy is genuinely useful operational information.

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 tightly written with three sentences, each contributing distinct value: purpose, usage examples, and retention/pairing details. It is front-loaded with the primary action, and no filler or redundant wording 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?

For a simple write operation with two parameters and no output schema, the description fully covers what the tool does, when to use it, persistence rules, and how it relates to recall and forget. It is complete enough for an agent to select and invoke the tool correctly without ambiguity.

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

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

Schema coverage is 100% with already descriptive parameter descriptions (e.g., 'Memory key (e.g., "subject_property")'). The description reinforces the key-value pairing but does not add substantial new meaning beyond the schema. It mentions 'scoped by your identifier' which touches on key namespace, but this is more behavioral context than parameter semantics, so a baseline score of 3 is appropriate.

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

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

The description opens with a specific action: 'Save data the agent will need to reuse later,' clearly identifying the verb and resource. It also distinguishes from siblings by stating 'Pair with recall to retrieve later, forget to delete,' which differentiates it from recall and forget. The scope (across conversations and sessions) adds precision.

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 conditions are provided: 'Use when you discover something worth carrying forward' with concrete examples like 'a resolved ticker, a target address, a user preference, a research subject.' It also gives complementary guidance on when to use recall (retrieve) and forget (delete), thereby covering alternatives within the tool family.

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 significant behavioral details beyond the annotations: multi-source cascade, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit 'unresolved' identifiers, and source labelling. It enriches the readOnly/idempotent hints with concrete lookup 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 well-organized, with a clear 'SUPPORTED TYPES' structure and no filler. Each sentence adds value, though its length might be slightly heavy for a quick scan.

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

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

It covers fallback behavior, unresolved fields, and what identifiers are returned, which is thorough given no output schema. However, it does not explicitly describe the full response format or error cases, leaving minor gaps.

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

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

While the schema covers parameter basics, the description adds substantial meaning: detailed source breakdown for 'company' (CIK, LEI, FIGI with ownership) and 'drug' (RxCUI with citation), plus examples for 'value'. This goes well beyond the simple enum and string descriptions.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with specific verbs and resources. It distinguishes from siblings by emphasizing it provides the IDs that other tools require as input.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID,' giving strong when-to-use guidance. However, it does not name specific alternative tools or state when not to use it, so it stops short of full explicit alternatives.

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

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

The description discloses internal behavior beyond the annotations: it probes each entity via ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. It also notes that the first entity is treated as the 'subject' for narrative purposes. These details are not present in the annotations (which only indicate read-only/idempotent behavior) and add significant transparency.

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

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

The description is four sentences, front-loaded with the core purpose, and each sentence provides distinct value (what it does, how it does it, when to use it, what it returns). No wordy or redundant content.

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

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

Given there is no output schema, the description compensates by listing the return fields (ranked list, score, confidence, signal density). It also covers internal mechanics, use-case fit, and parameter nuances. Combined with the strong annotations, an agent has enough to use the tool appropriately.

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 beyond the schema by clarifying that the first entity in 'entities' is treated as the subject and the rest are competitors, which affects the narrative output. It also makes the model selection clearer by mentioning free default vs. API key requirement, which the schema already includes but the description reinforces in context.

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 compares AI visibility across multiple entities, probes each with ai_visibility_check, and ranks them. It distinguishes itself from siblings like ai_visibility_check by focusing on side-by-side comparison and from compare_entities by specifying the AI-marketing use case and output (score, confidence, signal density).

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

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

It gives a concrete use case ('competitive AI-marketing audits' with the example 'does Claude know about us as well as our competitors?'), which makes the intended context clear. However, it does not explicitly mention when not to use the tool or name alternative tools (e.g., compare_entities), so it misses the full 'when-not/alternatives' 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 annotations already declare readOnlyHint and idempotentHint, but the description adds critical behavioral context: composite fan-out, graceful degradation, the 5-30s first-measurement delay on bundlephobia, and the sources_failed field on timeout. These details go well beyond what the structured annotations convey.

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 five sentences, each carrying distinct value: purpose, usage trigger, return structure, ecosystem scope, and failure handling. It is front-loaded with the primary purpose and contains 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 fully compensates by enumerating the return fields (summary block with specific metrics, per-advisory details, links, recent alternative versions) and explaining partial-failure behavior. This gives an agent enough context to know what to expect and how to handle edge cases.

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

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

The input schema has 100% coverage with detailed descriptions for both parameters, including scoped package acceptance and defaulting behavior. The description adds the ecosystem constraint (NPM-only in v1) but does not introduce new parameter syntax or meaning beyond what the schema already provides.

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

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

The description begins with a specific composite check definition, naming the two external sources (deps.dev and bundlephobia) and the exact user question it answers ('should I add this npm package'). It clearly lists the return elements, which differentiates it from sibling tools focused on AI visibility, research, or entity 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 states when to use it: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides a when-not condition ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), which serves as a clear alternative for non-NPM ecosystems.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior, so the bar is lower. The description goes beyond annotations by detailing the return structure (name, summary, record_count, owner/org, Feature Service URL) and the intended downstream usage, which is valuable behavioral context. It does not contradict annotations.

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

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

The description is two sentences, front-loaded with the main purpose. The first sentence states what it does; the second explains the return value and next step. No wasted words, clearly 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 simple search tool with no output schema, the description is complete: it covers purpose, return fields, and how to proceed. Annotations cover safety, and the schema covers parameters. The description meets all necessary context for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds minimal parameter-specific meaning (e.g., 'keyword' aligns with query, and the mention of Town of Chapel Hill aligns with org_id), but it does not go beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Search Town of Chapel Hill GIS open geospatial datasets by keyword.' It specifies the exact resource (Town of Chapel Hill GIS datasets) and the action (search). It also differentiates from siblings by noting the return of a Feature Service URL intended for use with query_layer/layer_info.

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 provides a usage workflow: after searching, 'pass that url to query_layer / layer_info.' This tells the agent when to use this tool (to discover datasets) and what to do next, effectively giving an alternative/next-step strategy. It also scopes the tool to Town of Chapel Hill GIS data.

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 rich behavioral details beyond the annotations: embedding model (BGE-base-en), similarity method (cosine), windowing (500-char overlapping), and input cap (200K chars with truncation flagging). It also explains that returned passages carry offsets for verbatim quote verification, which is not captured in annotations or schema.

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

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

The description is concise yet information-dense, typically 3 sentences. It front-loads the core purpose, then usage, then technical details. Every sentence adds value without fluff, achieving an ideal balance between brevity and completeness.

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

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

Despite having no output schema, the description adequately explains the return format (passages with offsets and similarity scores). It covers the core use case, behavior, and limitations (truncation). Combined with the rich parameter schema and annotations, the tool is well-specified for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, with clear descriptions for all three parameters (text, limit, query) including examples. The description does not add substantially new parameter semantics—it only restates the 200K char cap (already in schema) and the 'top-N' concept (already in limit description). Thus baseline 3 is appropriate.

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

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

The description clearly states the verb and resource: 'Semantic search INSIDE a fetched record.' It specifies the inputs (text + query) and outputs (top-N passages with offsets and similarity scores). It also distinguishes from siblings by pairing with ask_pipeworx_grounded and focusing on searching within already-fetched content.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also provides complementary guidance: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This clarifies the workflow and alternatives.

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

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

The description discloses significant behavioral context beyond annotations: the OAuth account requirement, phone verification for SMS, 10/day SMS cap, and webhook auto-disable after 10 consecutive failures. It also clarifies that feed is always on. These details complement the annotations (idempotentHint true, readOnlyHint false) without contradiction, providing a rich operational picture.

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 but front-loaded with the core purpose. Each sentence contributes details on types, requirements, or delivery options. The length is justified by the tool's complexity, though it could be broken into bullets for easier scanning.

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 rich schema and annotations, the description covers the essential aspects: purpose, types, prerequisites, delivery channels, and limits. It omits webhook as a delivery channel in the main prose (though schema covers it extensively) and does not specify the full response shape beyond the subscription id, but this is acceptable since no output schema exists and the tool is relatively straightforward.

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

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

Schema coverage is 100%, but the description adds interpretative value, e.g., items:['5.02'] = officer change for sec_8k, and provides concrete parameter examples for each type (topic:'fed', series_id:'UNRATE'). While much of this overlaps with the schema's per-type params descriptions, the example meanings enhance semantic clarity.

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 action ('Create a proactive monitoring subscription') and resource ('live-data event stream'), with explicit mention of the return value ('Returns the new subscription id'). It distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation and enumerating supported 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?

The description provides clear context on when to use the tool, including prerequisites (requires OAuth account), supported subscription types with examples, and delivery channels. It implicitly differentiates from alternatives by noting how to pull the feed (via recent_alerts or GET registry.pipeworx.io/alerts.json), but it does not explicitly state when not to use this tool or name alternative tools for one-time queries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it returns category-bucketed examples from the live catalog, includes the exact tool+argument shape, and supports a topic parameter to filter results. This goes beyond the annotations without contradicting them.

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

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

The description is longer than average but front-loaded with user-facing example questions that immediately convey intent. Every clause earns its place—purpose, return structure, and usage are covered. It could be trimmed slightly, but the structure is effective for an onboarding tool.

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

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

Even without an output schema, the description fully explains what to expect: category-bucketed example questions, exact tool+argument shape, and the ability to focus by topic. It also covers when to use it and mentions the meta-tools it helps introduce. For a read-only onboarding tool with one optional parameter, this is complete.

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

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

Schema coverage is 100%, and the description essentially reiterates the schema ('pass `topic` to focus', 'no arguments for the full spread'). It adds minor context by giving example values like 'finance', 'pharma', and 'betting', but does not introduce new semantics beyond the schema's inline description.

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

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

The description clearly states this is 'the onboarding entry point' and 'Returns category-bucketed example questions' with 'exact tool + argument shape'. It differentiates itself from siblings like ask_pipeworx and discover_tools by explicitly positioning itself as the tool to use when the agent doesn't yet know 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?

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'. Also provides concrete calling patterns: no arguments for the full spread, or pass a topic to focus. This is strong when-vs-alternative guidance.

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

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

Discloses important behaviors beyond the annotations: ownership is enforced, the row is deactivated not deleted, and historical events stay available via recent_alerts. This adds meaningful context that complements the idempotentHint and destructiveHint annotations.

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

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

Two sentences, front-loaded with the action, and each sentence adds distinct value (ownership, non-destructive deactivation). No redundancy or filler.

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

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

For a simple one-parameter tool with no output schema, the description covers the action, ownership constraints, side effects, and historical impact. It fully equips the agent to invoke the tool correctly.

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

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

The schema already provides 100% coverage for the single parameter, including that it is a uuid returned by subscribe. The description's 'by id' phrasing adds little beyond the schema, so it meets the baseline for high schema coverage.

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

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

The description uses a specific verb 'Cancel' with a clear resource 'a subscription by id', which precisely states the tool's function. It also differentiates from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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

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

Provides clear context about ownership enforcement (only cancel your own subscriptions) and the non-destructive nature (deactivated, not deleted). However, it does not explicitly mention alternatives or when not to use this tool, which would warrant 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 declare read-only, idempotent, open-world, and non-destructive. The description adds essential behavioral details: it explains each verdict outcome, clarifies that 'could_not_verify' means the check did not happen and must not be treated as evidence, and distinguishes 'unsupported'. It also discloses the fast-path for SEC/XBRL financial claims and fallback for all others, going well beyond 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 front-loaded with purpose and usage. It uses clear structure: examples, purpose, behavior, return values, caveats, and efficiency benefit. A few phrases like 'natural-language claim verification' are repeated, but every section adds value. It's appropriately verbose for a complex tool.

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

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

No output schema exists, so the description must explain return values — it does so by listing the verdict enum, the actual value with citation, and reasoning. It also covers edge cases (could_not_verify vs. unsupported) and gives an example claim. Combined with full parameter schema and rich annotations, the description is complete and self-sufficient.

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

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

Schema coverage is 100% for both parameters. The description references 'exact percent-delta math' but does not add new semantics beyond what the schema already provides for 'claim' and 'tolerance_pct'. Since the schema fully documents parameters, the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool's purpose as natural-language claim verification against authoritative sources. It provides explicit trigger phrases ('fact check', 'verify the claim that...') and specific behavior for company-financial vs. other claims. This distinguishes it from general research tools by focusing on verdicts with evidence.

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

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

The description states 'Use whenever the agent needs to check whether something a user said is factually correct' — clear usage context. It also implies alternatives by noting this replaces 4–6 sequential calls, but doesn't explicitly name sibling tools or mention when not to use it, so it's clear but not exhaustive.

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