Arcgis Hub

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the description doesn't need to repeat that. It adds valuable context about the default free model (Workers AI Llama-3.3-70b) and that probing Anthropic requires a user-supplied API key with direct billing, which is useful for cost awareness. No contradiction exists.

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

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

The description is three sentences, front-loaded with purpose, and every clause adds information: what it does, model defaults/billing, and use cases. 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?

Even with no output schema, the description details the per-model return structure ({score, confidence, signals, raw_response}) and the combined view. Combined with full parameter docs and strong annotations, this gives an agent a complete picture for selection and invocation.

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

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

Schema coverage is 100% with all four parameters described. The description goes slightly beyond the schema by explaining the default model and reinforcing that `_apiKey` is passed straight through, which adds semantic value without being redundant.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and produces a 0-100 visibility score per model, using a specific verb ('probe') and a defined resource/scope. It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on entity-level AI visibility scoring across multiple models.

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 concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and clarifies default vs. optional model selection, which gives clear context for when to use it. However, it does not explicitly mention alternatives or exclusionary conditions, 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 indicate a safe, read-only, idempotent, open-world operation. The description adds substantial beyond-annotation context: it routes through 5,407 tools, automatically fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and is one fast call. This gives the agent a clear picture of what happens under the hood.

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 two sentences but is well-structured with a strong front-loaded directive ('PREFER OVER WEB SEARCH') and a clear step-up section. There is some mild redundancy (e.g., 'START HERE' and 'default entry point'), but every major sentence provides useful guidance or examples.

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 as a meta-router over 5,407 tools, the description effectively covers scope, usage scenarios, sibling differentiation, and expected output (structured answer with citations). It compensates for the absence of an output schema by clearly setting expectations for what the agent will receive.

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

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

The input schema already has 100% coverage with a clear description of the question parameter and aliases. The description adds practical meaning by giving example questions and phrase cues that clarify what kinds of natural-language inputs are appropriate, thereby going beyond the schema baseline.

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

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

The description clearly states the tool routes questions to the appropriate specialized tool among 5,407 tools across 1403 verified sources and returns structured answers with citation URIs. It uses specific actions like 'routes' and 'returns', and distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research.

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

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

The description explicitly says to 'PREFER OVER WEB SEARCH' for a long list of factual topics, provides concrete query triggers ('what is', 'look up', 'find', etc.), and clarifies when to step up to alternatives: use ask_pipeworx_grounded for hallucination-resistant evidence-backed answers, or deep_research for broad multi-part questions. It also declares 'START HERE' as the default entry point.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable context: it is a full working router with no fallback, currently matching stable ask_pipeworx because no experimental candidate is active, and it highlights the experimental edge. This goes beyond annotations to convey real behavioral nuances and current state.

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

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

The description is dense and information-rich but slightly verbose. Sentences cover beta nature, current status, usage, and fallback behavior, with the key idea front-loaded. Each sentence earns its place, though it could be tightened slightly without loss.

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

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

For a router tool with no output schema, the description explains the relation to the stable version, the current candidate state, and the lack of fallback, which is sufficient for an agent to understand what to expect. It references 'same response shape' to capitalize on sibling knowledge, making it nearly complete.

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

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

Schema coverage is 100% with all six parameters documented as aliases for 'question' and a full description of the main field. The description adds no parameter-specific meaning beyond saying 'same arguments' as ask_pipeworx, which is not necessary given the schema is self-explanatory. 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 this is a beta version of ask_pipeworx, a universal router with 5,407 tools, and explicitly differentiates it from the stable sibling by noting it runs candidate routing improvements. It avoids tautology by explaining the tool's role and current state, making its purpose unmistakable.

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

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

The description explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and notes results are compared against the stable router. This provides clear when-to-use guidance and implicitly contrasts with the stable ask_pipeworx, covering the main alternative.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses detailed behavioral traits: extraction only from tool result, explicit refusal reasons, return shape with evidence and confidence, and the extra LLM call cost. These add significant context not available in annotations.

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

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

The description is dense but well-structured: opening summary, mechanism, return format, refusal reasons, usage scenarios, and cost trade-off. Every sentence is informative and earns its place. Despite being longer than average, it avoids fluff and front-loads the most critical information.

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

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

With no output schema, the description fully explains return values on success and refusal, including specific refusal_reason fields. It also covers the routing behavior, cost, and use cases, making the tool self-contained. The complexity of the tool (grounded extraction, refusal modes) is fully addressed.

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

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

Schema coverage is 100% with the question parameter and its aliases fully described. The description does not add additional parameter semantics, but since the schema already covers all parameters, the baseline of 3 is appropriate. The description focuses on behavior rather than parameters, which is acceptable given high schema coverage.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads. It specifies the verb (extracts answers) and resource (tool results from 5,407 sources), and distinguishes from the sibling ask_pipeworx by mentioning the extra LLM call and stricter grounding.

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

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

Explicit guidance on when to use: 'whenever an answer will be quoted, cited, or acted on' and when not: 'prefer ask_pipeworx for casual lookups.' It also mentions the cost trade-off and routing similarity to ask_pipeworx, giving clear alternatives.

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

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

The description goes far beyond the read-only/idempotent annotations by disclosing resolver contracts (market_match_confidence, alternatives, suggestions), safety short-circuits (low_confidence_match, market_closed_or_inactive), news fallback behavior (rate-limit handling), wide-spread illiquidity warnings, and resolution-rule risk (cancellation_rule). It also explains when analysis fields are suppressed, providing comprehensive behavioral insight. No contradiction with annotations.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It is front-loaded with the core purpose and each section provides critical operational details. While slightly verbose, the length is justified by the tool's complexity and the absence of an output schema.

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

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

With no output schema, the description fully specifies return shapes, resolver fields, parent-event extraction, news fallback markers (including _fallback_attempted), status codes, and cancellation-rule risk. It covers edge cases and safety mechanisms, making the tool's behavior self-contained and highly complete for an agent to use correctly.

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

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

The input schema already provides 100% coverage with rich descriptions for all three parameters (market, depth, include_raw). The main description reinforces market input formats but does not add new meaning beyond the schema; the added detail focuses on tool behavior and response shapes rather than parameter semantics. Per the baseline rule for high schema coverage, a 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 verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from sibling Polymarket tools by focusing on researching a single bet with evidence and provides explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z').

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 when to use the tool: 'Use for ...' with concrete question phrasings. It also provides classifier examples and fan-out behavior across domains. However, it does not explicitly name alternative tools or state when NOT to use it, so it doesn't fully differentiate from siblings like polymarket_edges or polymarket_arbitrage.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return format with citation URIs. This goes well beyond annotations without contradiction.

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

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

The description is dense but every sentence contributes: trigger phrases, usage preference, data details, sorting behavior, and return format. It is well-structured and front-loaded, making it easy to scan despite 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?

With no output schema, the description compensates by explaining return values ('paired data + pipeworx:// citation URIs per entity') and sorting. It covers key behavioral aspects and limitations (2–5 entities) implicitly through examples, making it complete for an AI agent to select and invoke correctly.

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

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

Schema coverage is 100%, but the description enriches the 'type' parameter by explaining what data each enum value pulls (10-K financials vs. FAERS/FDA data). It also gives concrete examples for 'values' (AAPL, MSFT, ozempic, mounjaro), adding practical meaning beyond the schema's generic descriptions.

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

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

The description clearly states the tool's function: side-by-side comparison of 2–5 companies or drugs in one parallel call. It uses specific verbs like 'compare' and provides natural-language trigger phrases, distinguishing it from sibling tools like entity_profile by explicitly favoring it for comparisons.

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

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

The description gives explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also differentiates between company and drug types, and notes that it replaces 8–15 sequential lookups, making the context and alternatives clear.

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

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

Even though annotations already indicate readOnly/openWorld/idempotent, the description adds extensive behavioral context: account/paywall requirements, parallel routing across 5,407 tools, output structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field), semantic excerpting behavior, and expected latency. No contradiction with annotations.

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

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

The description is dense and front-loaded with the most critical constraint (account required, use ask_pipeworx otherwise). While long, every sentence contributes meaningful operational or usage detail and the structure is logical (auth → core function → comparisons → depth behavior → latency).

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

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

Given the tool's complexity and absence of an output schema, the description thoroughly covers the return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation, gaps, contradictions, hop field), edge cases (breaking news yields gaps[]), and runtime expectations. It is sufficiently complete for an agent to invoke 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 schema already provides 100% coverage with detailed descriptions for both 'question' and 'depth', including enum meanings and the paid nature of 'thorough'. The description mostly repeats or rephrases schema content, adding little unique parameter information beyond what the schema already documents.

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 performs grounded multi-source research across Pipeworx's structured data sources in a single call, decomposing questions into facets. It explicitly distinguishes itself from open-web search and from simpler single-lookup tools like ask_pipeworx.

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

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

Provides explicit guidance: use for broad/multi-part questions over structured data, use ask_pipeworx for single lookups or breaking/current-news topics, and notes account/paid-plan requirements. Names alternatives directly and gives concrete examples.

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 safety (readOnly, idempotent, non-destructive), so description adds beyond that by disclosing return behavior: returns top-N tools with names, descriptions, full input schemas, and curated examples, with results ready to call directly without a second lookup. This is useful operational detail not present in annotations.

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

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

Three sentences, each earning its place: purpose, applicable domains, and return-value detail. Front-loaded with the core action, and the call-to-action ('Call this FIRST') is practical and succinct. No redundancy.

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

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

For a simple discovery tool with strong annotations and no output schema, the description covers purpose, when to use, what it returns, and how the results are structured. The lack of output schema is compensated by describing the return payload. It is fully adequate for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with aliases already documented, so baseline is 3. The description adds minimal parameter semantics—'top-N' maps to limit and 'describing the data or task' points to query—but these are already covered by schema examples. It does not substantially compensate 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 verb and resource: 'Find tools by describing the data or task.' It distinguishes this meta-tool from siblings by emphasizing discovery/browsing of available tools across many domains, and explicitly says 'Call this FIRST' to see the option set.

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 when-to-use 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 does not explicitly mention when-not-to-use or alternative tools by name, but the 'not just one answer' phrase implies a boundary.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses meaningful behavioral traits: it fans out across multiple sources in parallel, returns a specific set of fields, soft-fails for the USPTO API sunset, and uses a GDELT→GNews fallback. This enriches the agent's understanding of side effects and failure modes.

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

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

The description is dense but well-structured, front-loading usage examples and then detailing outputs and constraints. Every sentence adds relevant information (fallback behavior, input constraints, return fields), so it earns its length. It loses a point only because it is a single long paragraph that could be broken into scannable sections.

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

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

With no output schema, the description must explain return values, and it does so thoroughly: cik + company_name, recent_filings (up to 5 with URIs), fundamentals (LATEST 10-K fields), patents, news mentions, and LEI. It also covers edge cases (USPTO sunset, unsupported names, input formats), making it complete for a tool of this complexity.

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

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

The input schema already covers both parameters with descriptions, including the allowed enum for type and the ticker/CIK format for value. The description mostly repeats this, though it adds concrete examples ('AAPL', '0000320193') and reinforces the name-not-supported constraint. This is a minor increment, so a baseline 3 is appropriate.

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

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

The description opens with concrete user phrasings and states the core function: 'full cross-source profile of a US public company in ONE parallel call.' It clearly identifies the resource (US public company) and differentiates from sibling tools by explicitly preferring it over chaining single-pack SEC/XBRL/news lookups.

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

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

Explicit when-to-use guidance is present: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides clear exclusions: 'names not supported (use resolve_entity first if you only have a name)' and specifies input formats (ticker or zero-padded CIK).

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds usage rationales (clearing sensitive data) but does not disclose additional behavioral traits such as irreversibility or return behavior beyond what annotations imply.

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

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

Two sentences, front-loaded with purpose, no filler 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 single-parameter destructive tool with comprehensive annotations, the description covers purpose, usage, and positioning relative to siblings. No output schema is needed for such a tool.

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

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

Schema description coverage is 100%, with 'key' described as 'Memory key to delete'. The description reinforces 'by key' but adds no additional parameter semantics beyond the schema.

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

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

The description uses a specific verb ('Delete') and resource ('previously stored memory by key'), clearly distinguishing it from sibling tools like 'remember' and 'recall'.

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 context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with 'remember and recall', but does not provide an explicit when-not or direct alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, establishing the safety profile. The description adds valuable behavioral detail: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This goes beyond annotations by explaining the process and output format, with no contradictions.

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

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

The description is three sentences long, with no wasted words. It front-loads the core purpose, then explains the process, and ends with practical use cases. Every sentence earns its place, making it concise and well-structured.

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

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

For a simple 2-parameter tool with no output schema, the description is remarkably complete. It explains what the tool does, how it works (fetch/extract/emit), and what the output looks like ('a single text blob'). Combined with rich annotations, it gives an agent everything needed to decide when and how to invoke it.

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

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

The input schema fully describes both parameters (url and max_links) with clear descriptions and defaults, so schema coverage is 100%. The description itself adds no additional parameter-specific semantics, keeping it at the baseline for a fully self-documenting schema.

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

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

The description opens with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It clearly states the tool's function and differentiates it from sibling tools like scan_competitor_ai_presence by focusing on the output artifact (llms.txt) rather than merely checking AI visibility.

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

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

The description provides three concrete use cases: getting a client's site indexed, drafting llms.txt for a project, and auditing how a competitor appears to AI crawlers. This gives clear contextual guidance, though it does not explicitly mention when not to use the tool or point to alternative sibling tools.

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

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

Annotations already provide readOnly, idempotent, openWorld, and non-destructive hints. The description adds valuable context about the actual return payload (fields, geometry type, record count, capabilities), which helps the agent anticipate output. There is no contradiction with annotations, and the added detail goes beyond the basic 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 single, tightly packed sentence that front-loads the purpose and enumerates the exact outputs. There is zero waste; every word contributes to understanding the tool's function.

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, no output schema), the description is highly complete. It explains both what the tool does and what it returns, covering the essential aspects an agent needs. Annotations cover safety, so no further behavioral disclosure is needed.

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

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

The schema already provides a thorough description of the 'url' parameter, including an example and the expected format ('.../FeatureServer/0'). The description only repeats 'by url' without adding new semantic information. With 100% schema coverage, the baseline score of 3 is appropriate.

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

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

The description uses a specific verb 'Get' and names the exact resource: an ArcGIS Feature/Map Service layer's schema. It lists concrete returned elements (fields with name+type, geometry type, total record count, capabilities), which clearly distinguishes it from the sibling tool 'query_layer' that presumably fetches data.

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

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

The context is clear: this tool is for retrieving schema/metadata, not data rows. However, it does not explicitly name alternatives or state when NOT to use this tool. Since the use case is obvious (schema retrieval), it earns a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds behavioral context by specifying the caller's subscriptions, the returned fields, and the default active-only scope.

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

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

Two concise sentences: the first states the action and return format, the second provides usage guidance. No redundant information.

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

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

For a simple list operation with one optional parameter and no output schema, the description covers all essential aspects: scope, return fields, and usage context. The schema and annotations fill in safety and parameter details.

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

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

The input schema covers the only parameter, include_inactive, with a clear description including default behavior. The tool description adds no extra parameter semantics, so baseline 3 applies.

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

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

The description clearly states the tool's function with a specific verb and resource: 'List the caller's active subscriptions.' It also enumerates the return fields, distinguishing it from subscription management siblings like subscribe/unsubscribe.

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

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

It provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use it, though it doesn't name alternative tools or specify when not to use it.

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

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

Annotations are all false, so the description carries the burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and impact ('signal directly affects roadmap'). This adds useful behavioral context beyond the basic non-destructive nature implied by the tool's purpose.

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 and front-loaded: first sentence states the core action, followed by usage scenarios, a formatting tip, and operational constraints. Every sentence earns its place, with no redundant or filler content.

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

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

For a simple feedback tool with 3 parameters (2 required, one enum, one nested object) and no output schema, the description covers all essential aspects: what it does, when to use it, how to structure the feedback, and operational limits (rate limit, quota). It 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%, so the baseline is 3. The description adds meaningful guidance for the 'message' parameter ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), which helps the agent formulate appropriate feedback. It also reinforces the purpose of the 'type' enum through examples.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('tell') and resource ('Pipeworx team'), and distinguishes itself from sibling tools by being the feedback channel for bugs, features, data gaps, and praise.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a negative instruction ('don't paste the end-user's prompt'), clarifying boundaries.

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 detail beyond the annotations: it explains the data source ('CF analytics-engine'), privacy characteristics ('no PII'), return shape ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). These are meaningful behavioral disclosures not present in annotations.

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

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

The description is front-loaded with the core purpose, then uses a compact bulleted 'Useful for' list. It is information-dense without being verbose; every sentence adds value, including cache and privacy details.

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

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

For a simple read-only aggregator with one optional parameter, the description covers purpose, return contents, data source, privacy, and cache behavior. Even without an output schema, the agent has enough context to 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 schema already documents the window parameter with full coverage, but the description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose the right window for different use cases.

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

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

The description clearly identifies the tool as returning trending agent call data ('Returns the top tools, top packs, and total call volume') over a recent window. It distinguishes itself from siblings like discover_tools by emphasizing it is a self-aggregating signal of current agent behavior.

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

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

The 'Useful for' list provides explicit scenarios for when to use the tool: discovering hot data sources, confirming a canonical tool, and checking alignment with agent needs. It does not name alternatives or exclusions, but the use cases are clear enough to guide 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?

Beyond the read-only/idempotent annotations, the description discloses substantial behavioral traits: the no-args trending scan, the walking of child markets, Jaccard similarity thresholds, placeholder filtering, and the fill check against live CLOB depth. It even warns 'do not trade it' when realizable edge is non-positive, providing actionable behavioral context.

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

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

The description is long but highly structured with uppercase section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a clear flow from purpose to modes to response details. Each sentence adds unique information, so while dense, it is not wasteful. The front-loading of the primary purpose and mode selection helps quick comprehension.

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

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

For a complex tool with two modes and no output schema, the description is remarkably complete. It covers the default behavior, each mode's logic, edge cases (placeholder slugs, low similarity), response fields (opportunities[], partition_check), and the relationship to polymorphic fill checking. This gives an agent all necessary context to invoke the 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?

Although the schema already documents both parameters, the description adds crucial semantic depth: what constitutes a valid event slug with examples, how topic performs a cross-event search, and the fact that calling with no arguments triggers the trending scan. This is far more than the schema provides, instructing the agent on parameter formats and the no-arg behavior.

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.' This clearly identifies what the tool does and its method. It also distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection and even referencing polymarket_fill_risk for custom sizing.

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

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

The description provides explicit when-to-use guidance: no args for trending_scan, 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It additionally explains what each mode is best for and directs users to 'polymarket_fill_risk' for custom sizing, making alternative choices clear.

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

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

The description provides extensive behavioral detail beyond the annotations: it explains the five model families divided into three response segments, the edge_pp_net calculation net of slippage, Kelly fraction capping at 0.25, the 24h-move warning, and KV-level caching keyed on knobs. It also discloses the response structure including by_segment, fed_candidates/fed_note, and _diagnostics, which is crucial since no output schema exists.

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

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

The description is long but well-structured with section-like uppercase labels (FIVE MODEL FAMILIES, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and front-loaded with the primary purpose. Every sentence contains substantive information, though its density makes it slightly less concise than ideal.

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

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

Given the tool's complexity (9 parameters, no output schema), the description covers nearly all necessary context: the full response top-level structure, filtering knobs, diagnostics for empty segments, the Fed note caveat, and caching behavior. It even explains why a segment might be empty (top-N stale, gates failed, knobs dropped). This is highly complete for an agent to invoke and interpret results correctly.

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

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

The input schema already has 100% parameter coverage, providing a baseline of 3. The description adds meaningful interaction details that go beyond the schema: e.g., min_partition_leg_kelly applies to per-leg Kelly because partition arbitrage always returns parent kelly_fraction_half=0, and min_kelly never filters partition arbs. These clarifications improve understanding of how knobs work together, so a score of 4 is warranted.

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

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

The description opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price', which is a specific verb+resource+scope statement. It also distinguishes itself from siblings by stating it's built for 'what should I bet on today' and avoids paging hundreds of markets, clearly separating it from tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description gives clear context for when to use this tool: to discover betting opportunities from top Polymarket markets without manually paging through hundreds. It doesn't explicitly name alternatives or when-not-to-use, but the use case is unambiguous, so it qualifies as 'clear context, no exclusions'.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses numerous behavioral details: snapshots written on cache-miss, 60-day TTL, decay computed from daily closes of edge_pp_net, signed value meaning, and response semantics. This is rich disclosure of how the tool behaves, well beyond what annotations provide.

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

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

The description is well-structured with clear sections (purpose, args, RESPONSE, LIMITS) and is densely informative. Every sentence contributes value: it explains the core question, parameter defaults, response fields, and limitations without fluff. Front-loaded with the main use case.

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

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

There is no output schema, so the description fully documents the return structure: tracked[] with fields, expired[], and snapshot_dates[]. It also covers limitations (TTL, snapshot availability, decay calculation). For a complex telemetry tool, this is a complete description.

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

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

Schema coverage is 100% (both parameters have descriptions with defaults and constraints). The description restates days and window defaults and adds 'snapshot family' context, but this largely mirrors the schema. No new semantic meaning is added beyond what the input 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 states a specific purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and explicitly answers 'how long has this edge existed and is it shrinking?' This clearly distinguishes it from siblings like polymarket_edges by focusing on persistence/decay over time.

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

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

The description provides clear context for when to use the tool: to differentiate fresh wide edges from old wide edges ('a fresh wide edge and a 3-week-old wide edge are different trades'). It implies the tool is for assessing edge age/decay, but does not explicitly name alternatives 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?

Beyond the strong annotations (readOnly, openWorld, idempotent, non-destructive), the description adds crucial behavioral context: it explains partial basket fill risks, "theoretical overround on thin books is not capturable," and describes the return verdicts (clean|degraded|cannot_fill). This goes well beyond what annotations provide and is essential for understanding the tool's behavior in real trading scenarios.

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 quite long, but it is well-structured with clear mode labels (SINGLE-MARKET, BASKET) and a front-loaded opening sentence. Each section adds value, especially the risk rationale in the final sentence. However, it is verbose and could be tightened, so it does not earn a 5 for conciseness.

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

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

With no output schema, the description carries the full burden of explaining return values. It does so comprehensively for both modes, listing all key outputs (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], etc.). It also covers edge cases like minimum fill thresholds and directional risk, making the description complete for a complex tool.

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

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

Schema coverage is 100%, and the description largely repeats the schema's parameter descriptions (e.g., size_usd semantics, side defaults). While the description weaves the parameters into the mode explanations, it does not add substantial new meaning beyond what the schema already declares. The baseline of 3 is appropriate given the high schema coverage.

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

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

The description opens with a specific, informative statement: "Realizable-vs-theoretical edge check against live CLOB order-book depth." This clearly identifies the tool's purpose and resource. It also differentiates from siblings by referencing polymarket_arbitrage and polymarket_edges, and explicitly states when to use this tool before acting on those signals.

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

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

The description provides explicit when-to-use guidance: "USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500." It gives clear context and rationale, but does not explicitly mention when not to use it or name alternative tools for specific scenarios, so it falls short of a perfect 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?

With annotations already declaring readOnlyHint=true and idempotentHint=true, the bar for additional disclosure is lower, but the description goes far beyond them. It details compatibility_warning conditions (matched_pairs:0 with skipped_cross_type > 0 vs. matched_pairs:0 with skipped_cross_type:0), temporal_alignment semantics, and skipped_cross_type/subtype counters, explaining what these mean for the validity of the spread. This is rich behavioral context that annotations alone could not provide.

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

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

The description is long but well-structured: it progresses from the core concept to modes, response, safety fields, and a final caveat. Each sentence contributes meaningful information, and complex concepts like compatibility_warning are broken down clearly. It loses a point for length and some redundancy (e.g., 'pre-mapped ≠ tradeable' repeats the earlier warning), but it remains efficient for the tool's complexity.

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

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

Despite having no output schema, the description thoroughly covers response fields (leg-by-leg prices, top_spreads_pp), error/warning indicators (compatibility_warning, temporal_alignment), and edge cases (matched_pairs:0 scenarios, skipped counters). It explains the mathematical meaning of spreads (temporal alignment false = meaningless) and the limitations of pre-mapped topics. This is a complete picture for an agent to invoke the tool correctly.

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

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

The schema already provides descriptions for all three parameters with examples, so baseline is 3. The description adds value by explaining the two operational modes (topic vs. explicit ticker/slug), clarifying that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and listing the exact shortcut values for topic. This enriches the semantic understanding beyond the schema, earning a 4.

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

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

The description opens with a clear statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which identifies both the resource (the two venues) and the operation (computing a spread). It further distinguishes itself from sibling tools like polymarket_arbitrage by emphasizing cross-venue comparison rather than single-venue analysis. The two-mode (topic vs explicit ticker/slug) structure is clearly outlined, leaving no ambiguity about what the tool does.

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

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

The description provides explicit usage modes ('TWO MODES') and warns that most pre-mapped topics return compatibility_warning today, giving practical caution. However, it does not explicitly name sibling tools as alternatives (e.g., 'use polymarket_arbitrage for single-venue spread analysis'), so it misses the 'when-not/alternatives' level of a 5. The context for when to use it vs. not is clear, just without direct tool-to-tool comparisons.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds value by specifying the return type ('attribute rows (and geometry)') and the SQL-like query semantics, which goes beyond the structured data.

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

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

The description is two sentences: the first states purpose and key parameters, the second gives a practical tip. Every word contributes, with no redundancy or fluff.

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

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

For a query tool with 6 parameters, it covers purpose, parameter list, return type, and a usage pattern. It does not mention authentication or rate limits, but the readOnlyHint annotation and the absence of an output schema reduce the burden. It is complete enough for straightforward 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?

The schema documents all parameters with details and examples, so baseline is 3. The description adds a useful tip for sampling (where="1=1" + out_fields="*") and classifies the where clause as SQL-like, but these are marginal enhancements over the schema.

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

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

The description clearly states the action ('Query'), the resource ('ArcGIS Feature Service / Map Service layer'), and the prerequisite source of the URL ('from search_datasets'). This differentiates it from sibling tools like search_datasets (finding layers) and layer_info (metadata).

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 mentions that the URL comes from search_datasets, establishing a clear workflow. It also provides a concrete sampling pattern. It does not explicitly state when not to use it or mention alternatives, but the context is sufficient for an agent.

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. The description adds useful behavioral context: scoping to 'your identifier (anonymous IP, BYO key hash, or account ID)' and the list-all behavior when key is omitted. However, it does not mention behavior for missing keys or errors, which is a minor gap.

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

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

Three sentences, each earning its place. The first sentence states the core functionality, the second gives use-case context and examples, and the third covers scoping and relationships. No filler, front-loaded with the main action.

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 with no output schema, the description is mostly complete: it explains both modes (retrieve/list), scoping, and relationship to siblings. The only gap is not specifying what happens when a provided key is not found, which could leave an agent uncertain about 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?

Schema coverage is 100%, so baseline is 3. The description adds context beyond the schema by explaining that keys are saved via remember and providing examples of what might be stored. It reinforces the optionality of the key, adding value without repeating the schema's brief description.

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

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

The description clearly states the tool's action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)'. It uses a specific verb and resource, and distinguishes itself from siblings by explicitly naming remember and forget.

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

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

Provides explicit guidance on when to use: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' Also describes relationships with alternatives: 'Pair with remember to save, forget to delete.'

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

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

The description discloses important behavioral traits beyond the annotations: each alert carries source, citation_uri, and raw payload; mark_read:true affects subsequent calls by only showing newer events; and the feed persists. This adds significant context to the readOnlyHint and idempotentHint annotations, explaining the state-changing side effect of mark_read. No contradiction with annotations.

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

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

The description is three sentences, front-loaded with the main purpose, and every sentence adds substantive details. It packs a lot of info without fluff and maintains a clear structure.

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 read tool with good annotations and a comprehensive schema, the description is unusually complete: it explains return field semantics, filtering, state-changing behavior, and polling suitability, plus an alternative raw endpoint. No output schema exists, but the return fields are described sufficiently.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful semantics beyond the schema: it clarifies that type filters to one subscription type with an example, explains since as 'fired_at >= this time', and gives the consequence of mark_read:true (next call only shows newer ones). This helps agents choose and set parameters intelligently.

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

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

The description opens with 'Pull fired events from your subscription feed,' a specific verb+resource statement that immediately distinguishes it from sibling tools like list_subscriptions or recent_changes. It clearly identifies the resource (alerts on the persisted feed) and the action (retrieval).

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

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

The description gives clear context on when to use the tool: to retrieve recent alerts from a subscription feed, with optional filtering by type and ISO timestamp. It also provides usage guidance on mark_read and notes that polling works fine, though it doesn't explicitly mention alternatives among sibling tools. It does mention an alternative HTTP endpoint, which is an alternative access method.

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

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

Despite strong annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds substantial behavioral detail: it fans out to SEC EDGAR, GDELT→GNews fallback with rate-limit/5xx conditions, and USPTO soft-failure due to API sunset. It also describes the output structure (changes[] grouped by source, total_changes, pipeworx:// URIs), going well beyond the annotations.

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

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

The description is front-loaded with the most common natural-language triggers, then explains the core behavior, sources, input format, output, and alternative in a dense but logical progression. Every sentence contributes unique information—no filler or repetition.

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

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

Given there is no output schema, the description adequately covers return structure (changes[] by source, total_changes, citation URIs) and caveats (e.g., PatentsView soft-fail). It also explains data source selection and fallback, which is essential for understanding the tool's behavior. The description is complete for a tool of this complexity.

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

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

The input schema already provides 100% coverage for all three parameters, including format examples for `since` and `value`. The description adds extra value by recommending typical monitoring windows ('30d' or '1m') and explaining the fallback logic tied to `since`, but most parameter meaning is already in the schema, so a 4 is appropriate rather than a 5.

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

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

The description clearly identifies the tool as a 'change feed for a company in the last N days/weeks/months' and lists concrete user intents ('What's new with X', 'updates on Acme'). It explicitly distinguishes itself from the sibling tool entity_profile, meeting the 'specific verb+resource+scope' and sibling differentiation criteria.

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

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

The description gives explicit use cases with example queries and provides a direct alternative: 'Use entity_profile instead when you want the static profile...'. It also offers practical parameter guidance (e.g., 'Use "30d" or "1m" for typical monitoring'), making when-to-use crystal clear.

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

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

Goes beyond annotations by disclosing persistence behavior (authenticated vs anonymous sessions, 24-hour retention) and key-value scoping by the agent identifier. It could have explicitly mentioned overwrite behavior, but the idempotent annotation plus key-value semantics imply 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?

Three sentences, each serving a distinct purpose: purpose, usage guidance, and storage details. Front-loaded and free of unnecessary filler.

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

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

For a simple 2-parameter storage tool, the description covers purpose, use cases, persistence semantics, and related companion tools. Annotations cover idempotency and non-destructiveness, so no additional behavioral detail is needed.

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

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

Input schema already provides full coverage with descriptions and examples for both key and value. The description does not add parameter-specific constraints or formats, so a baseline of 3 is appropriate.

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

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

The description uses the specific verb 'Save' and clearly defines the resource as data needed later, across conversations or sessions. It distinguishes itself from sibling tools by explicitly mentioning pairing with recall and forget.

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

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

Provides explicit guidance with concrete examples ('a resolved ticker, a target address, a user preference, a research subject') and states when to use it ('Use when you discover something worth carrying forward'). It also clarifies how it relates to recall and forget.

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. The description adds valuable context beyond that: it accepts multiple input forms, auto-disambiguates, internally cascades through multiple lookup endpoints, and returns specific fields plus citation URIs. This gives a full picture of the tool's behavior without contradicting annotations.

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

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

The description is moderately long but well-structured: it opens with user-intent examples, then states purpose, then breaks down supported types with return details, and ends with an efficiency note. Every sentence adds value, but it could be slightly tightened without losing information.

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

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

For a two-parameter tool with no output schema, the description is exceptionally complete: it explains return values (ticker, CIK, company_name, RxCUI, ingredient, brand), citation URIs, input formats, disambiguation behavior, and internal cascading. An agent has all necessary context to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances understanding by explaining what each type returns (ticker+CIK vs RxCUI), what input forms are accepted, and providing concrete examples like 'AAPL' and 'ozempic'. This goes beyond the schema's terse property descriptions.

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

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

The description uses specific verbs ('resolve', 'look up') and clearly states the resource: converting user-spoken names to canonical/official identifiers needed by other tools. It also distinguishes itself from siblings by positioning itself as the first step for ID lookup, with examples of target entities (ticker, CIK, RxCUI).

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 'Use FIRST whenever you have a name but need an ID' and provides trigger examples, giving clear when-to-use guidance. It does not explicitly name alternatives or when-not-to-use scenarios, but the context is strong enough for an agent to decide.

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 this safe (read-only, idempotent, non-destructive). The description adds meaningful behavioral detail by explaining that the tool probes each entity via ai_visibility_check, ranks results, and surfaces most/least recognized entities. This goes beyond annotations, though it doesn't mention potential network/cost implications.

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-organized: it opens with the core purpose, follows with the process, adds a practical use case, and finishes with the output structure. Each sentence earns its place with no redundancy.

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

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

For a read-only comparison tool, the description is highly complete. It explains what the tool does, how it works, when to use it, and what it returns (ranked list with score, confidence, signal density). Combined with the comprehensive schema and annotations, an agent has all necessary context for correct selection and invocation.

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

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

Schema coverage is 100% with each parameter well-described (models, _apiKey, context, entities). The description adds no significant parameter-specific detail 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 clearly states a specific verb ('Compare') and resource ('AI visibility across multiple entities'), and offers a concrete example use case ('does Claude know about us as well as our competitors?'). It distinguishes itself from siblings like ai_visibility_check by emphasizing side-by-side comparison and ranking.

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

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

The description provides a clear context for use ('competitive AI-marketing audits') and implies the tool is for comparing multiple entities, contrasting with the single-entity sibling ai_visibility_check. However, it lacks explicit 'when not to use' or direct alternative comparisons, so it falls short of a perfect score.

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

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

Discloses external fan-out, a 5-30s latency on first bundlephobia measurement, graceful degradation with sources_failed, and the npm-only limitation. These add meaningful context beyond the annotations (readOnly, openWorld, idempotent). 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 first sentence front-loads the core purpose, followed by usage, return structure, and limitations. Every sentence carries substantive info with no filler, and the dense content is organized using dashes and parentheticals effectively.

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

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

Despite lacking an output schema, the description enumerates the summary block fields, failure modes, ecosystem limits, and provides latency expectations. It covers all critical aspects for an agent to decide 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 descriptions already cover both parameters at 100%, providing parameter names and defaults. The description adds no additional parameter-specific 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 states a composite check for adding npm packages, with specific data sources (deps.dev and bundlephobia) and explicit output fields (license, advisories, bundle size, etc.). It distinguishes from siblings by scoping to npm and naming the exact checks performed.

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 whenever an agent asks...' with concrete example queries, and for non-npm ecosystems it names the direct alternative (deps.dev:version). This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare safety (read-only, idempotent, non-destructive). The description adds the return structure (name, summary, record_count, owner/org, Feature Service URL) and a clear behavioral note about passing the URL to query_layer/layer_info. It does not discuss potential result count limits or edge cases, but the added context goes beyond the annotations.

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

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

The description is two sentences, front-loaded with the primary action and then adding optional scoping and return details. Every sentence contributes meaning, with no fluff or redundancy.

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

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

For a search tool with 3 parameters and no output schema, the description covers the core behavior, optional scoping, return fields, and downstream usage. It does not describe edge cases (like no results) or exact response format, but the mention of downstream tools and fields gives sufficient context for an agent to use it 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%, so the schema already explains all three parameters. The description mentions org_id as 'an ArcGIS orgId' and scoping, but this largely restates the schema's description ('Optional ArcGIS orgId to scope results to one publisher'). No additional semantic value beyond the schema is provided.

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

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

The description states a specific verb ('Search'), a resource ('ArcGIS Hub catalog of open government geospatial datasets'), and the scoping mechanism (keyword, optionally org_id). It distinguishes itself from siblings by explicitly mentioning query_layer and layer_info as downstream recipients of the returned URL.

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

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

It clearly explains when to use the tool: for keyword-based discovery of geospatial datasets, optionally scoped to an organization. It also gives implicit guidance on next steps by pointing to query_layer/layer_info for further data access. However, it does not explicitly state exclusions (e.g., 'when not to use' or compare with search_within), 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=true and idempotentHint=true, but the description adds rich behavioral detail: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and a 200K char cap with truncation flagging. Also explains that every passage carries offsets for quote verification, which is valuable 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 about five sentences and covers purpose, usage, pairing, and internals. It is slightly dense, but each sentence earns its place and the structure flows logically from what the tool does to when to use it to technical mechanics. Loses one point for not being more compact, but it is far from rambling.

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 explains what the agent gets back: top-N passages with character offsets and similarity scores. It also covers input limits, pairing strategy, and the use case, so the agent has everything needed to invoke the tool correctly.

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

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

Schema coverage is 100%, so the default baseline is 3. The description enhances the schema by explaining that 'text' is a document you've already fetched, provides natural-language query examples, and clarifies the cap and truncation behavior for the text parameter. This adds practical meaning beyond the schema's bare property descriptions.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' a specific verb+resource statement that clearly distinguishes this tool from siblings like ask_pipeworx or search_datasets. It also mentions pairing with ask_pipeworx_grounded, reinforcing its unique role as a passage-level retriever.

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

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

The description explicitly states when to use this tool: 'Use when the record is too big to cram into the prompt,' and contrasts it with grounding over the whole document via ask_pipeworx_grounded. This gives the agent actionable guidance on choosing between sibling tools.

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

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

Despite existing annotations (readOnlyHint false, idempotentHint true, etc.), the description adds significant behavioral context: OAuth account requirement, anonymous/BYO restrictions, phone verification for SMS, 10/day cap, webhook signature and one-time secret, and auto-disable after consecutive failures. This exceeds what annotations convey and helps set 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 appropriately detailed for a complex subscription tool. It front-loads the core purpose and return value, then logically organizes requirements, types, and delivery options. Every sentence contributes new info 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?

No output schema exists, so the description must explain return values; it does (subscription id, webhook secret shown once). It also covers preconditions (OAuth, verified phone), per-type filters, and delivery behavior, making it fully sufficient for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, but the description enriches each parameter with concrete usage examples: sec_8k items like ["5.02"], polymarket_edge topic, fred_series series_id, plus detailed delivery channel semantics (email formatting, phone verification, webhook signing). This adds meaning beyond the schema's field descriptions.

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

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

The description opens with a precise action: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly identifies the resource (subscriptions/alerts), the verb (create), and the outcome (returns the new subscription id). This distinguishes it from sibling tools like list_subscriptions or unsubscribe.

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

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

The description gives strong context on how to use the tool, including supported subscription types with examples and delivery channels. It references recent_alerts for pulling the feed, which indirectly shows when to use other tools. However, it does not explicitly name alternatives like list_subscriptions for viewing existing subscriptions or unsubscribe for removal, so it stops short of a 5.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the return format (category-bucketed example questions with exact tool + argument shape), that results come from the live catalog, and that topic filters the output. This is rich behavioral context for a tool with no output schema.

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

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

The description is well-structured and front-loaded with the 'onboarding entry point' label, but the opening list of alternate questions ('what can you do?', etc.) adds some verbosity without essential information. Still, each sentence contributes value in clarifying intent and output.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete: it explains what the tool returns, how to call it, when to use it, and how it relates to other tools. 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 defines the 'topic' parameter fully with examples and a note to omit for cross-category spread. The description adds only 'e.g. finance, pharma, betting' which is largely redundant, so it doesn't add significant meaning beyond the schema.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point for an agent to learn what to ask Pipeworx. It specifies the resource (Pipeworx capabilities) and the action (returns example questions), and distinguishes itself from siblings like ask_pipeworx by explaining it provides tool + argument shapes rather than performing queries.

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

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

The description gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning to call meta-tools. It also explains the two modes: no arguments for full spread, or pass topic to focus, and names alternatives (ask_pipeworx, entity_profile, compare_entities) for context.

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

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

Annotations already flag readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds meaningful behavior beyond annotations: ownership enforcement and the deactivation-not-deletion semantics, which directly address the non-destructive nature and side effects.

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 tight sentences, front-loaded with the action, and every clause earns its place. No fluff or repetition.

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

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

For a single-parameter tool with no output schema, the description captures the key outcomes: ownership, deactivation, and preservation of historical events. It does not detail return values or error conditions, but the schema and annotations provide enough structure for an agent to act.

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 id parameter fully described as 'Subscription id (uuid) returned by subscribe.' The description adds no parameter-specific detail beyond 'by id', so the baseline of 3 is appropriate.

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

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

The description uses a specific verb+resource ('Cancel a subscription by id') and clearly distinguishes from siblings like subscribe and list_subscriptions. It also clarifies that this deactivates rather than deletes, which adds further purpose nuance.

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 conveys clear usage context: cancel your own subscriptions, and notes that historical events remain available via recent_alerts. However, it does not explicitly name alternatives or provide when-not guidance, though the context makes it largely implicit.

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

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

Despite annotations already declaring read-only and idempotent, the description adds substantial behavioral detail: the routing logic (SEC EDGAR fast path vs. grounded pipeline), the exact verdict set, the inclusion of pipeworx:// citations, and the note that it replaces sequential calls. 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 moderately long but front-loaded with the purpose and examples. Each sentence adds useful information about behavior, routing, or output. Could be slightly tightened by trimming some redundancy between 'natural-language claim verification' and later 'grounded pipeline' wording, but it remains efficient.

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

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

With no output schema, the description fully explains the return values (verdict, actual value, citation, reasoning). It also covers when to use, how claims are routed, and the tolerance behavior. For a complex tool with no structured output schema, this 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?

The schema covers both parameters with detailed descriptions (claim examples, tolerance_pct range and default). The description doesn't add new parameter semantics beyond the schema; it reinforces the behavior but doesn't explain parameters further. Baseline 3 applies because schema coverage is complete.

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

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

The description starts with multiple natural-language invocation patterns, then states a specific verb+resource: 'natural-language claim verification against authoritative sources.' It clearly distinguishes this from sibling tools by emphasizing it replaces 4-6 sequential calls and handles both structured SEC/XBRL fast path and grounded pipeline for all other claims.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and differentiates two claim types (company-financial vs. other). It does not name alternative tools or explicitly say when not to use, but the usage context is clear and concrete.

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