Arcgis Mckinney

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

Annotations indicate readOnly, idempotent, openWorld, non-destructive behavior, so the description doesn't need to reiterate these. It adds useful context: the free default model, BYO key for Anthropic, and the returned data structure (per-model {score, confidence, signals, raw_response} + combined view). No contradiction.

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

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

Description is a single paragraph of 4-5 sentences, front-loaded with the primary action. It covers essential points without verbosity. Could be slightly more structured (e.g., bullet points for use cases), but remains concise and informative.

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

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

With no output schema, the description adequately explains the return format (per-model + combined view). It addresses all parameters, default behavior, key usage scenarios, and the API key privacy aspect. No gaps given the tool's complexity.

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

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

Schema description coverage is 100%. Description adds value beyond the schema by clarifying defaults (omit models for workers-ai), the role of _apiKey (straight-through to Anthropic), and the disambiguation purpose of context. Each parameter gains additional practical guidance.

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

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

Description clearly states the action ('probe one or more LLMs'), the target ('business / brand / product / topic'), and the output ('score visibility (0-100)'). It distinguishes this tool from siblings by its specific focus on AI visibility scoring, not general research or entity resolution.

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

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

Explicitly explains default model usage and optional Anthropic key pass-through, plus lists use cases (AI-marketing audits, pre-launch checks, competitive monitoring). Does not explicitly mention when not to use or compare with siblings like 'scan_competitor_ai_presence', but the context is clear enough.

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 annotations (readOnlyHint, openWorldHint, etc.), the description adds behavioral context: it routes questions to 4,476 tools across 1,127 sources, returns structured answers with citation URIs, and notes it's fast and works on every tier. No contradictions with annotations.

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

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

The description is long but well-structured, with a clear front-loaded preference statement, examples, and differentiation from siblings. Every sentence adds value, though it could be slightly more concise without losing content.

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

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

The description is comprehensive given the complexity of the tool. It explains the return format (structured answer with citation URIs), covers when to use alternatives, and provides diverse examples. No output schema exists, but the description sufficiently explains what users can expect.

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

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

Schema coverage is 100% with all parameters described. The description adds value with examples but does not elaborate on parameter semantics beyond what the schema provides. However, the examples and usage context elevate it slightly above baseline.

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

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

The description clearly states the tool's purpose: answering factual questions about current or historical data from authoritative sources. It specifies the domain (SEC filings, FDA data, etc.) and distinguishes itself from web search, providing a clear verb-resource pair and scope.

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

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

The description provides explicit guidance on when to use this tool (default for most factual questions, start here) and when to use alternatives (ask_pipeworx_grounded for hallucination-resistant, deep_research for broad multipart, etc.). It also lists example queries and recommends this 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?

The description details behavioral traits beyond annotations: it costs an extra LLM call, extracts answers only from tool results, returns a structured response with evidence, confidence, and refusal reasons. This adds significant context to the existing annotations (readOnlyHint, idempotentHint).

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 thorough and well-structured, with the primary purpose front-loaded, followed by behavior details and usage guidelines. While it is somewhat verbose, every sentence adds value. A small omission would not harm clarity.

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

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

Given the tool's complexity and lack of output schema, the description adequately covers purpose, routing, behavioral details, refusal reasons, and cost. It compares with a sibling tool and provides domain examples, making it sufficiently complete for an AI agent to use correctly.

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

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

The input schema has 6 parameters but all are aliases for 'question', with 100% description coverage. The description does not add new semantic meaning beyond what the schema already provides for parameters, 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 that this tool is a 'Hallucination-resistant answer mode for high-stakes reads', explaining it uses the same routing as ask_pipeworx but extracts answers only from tool results. It distinguishes itself from ask_pipeworx as a grounded variant for when answers will be quoted or cited.

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 this tool 'whenever an answer will be quoted, cited, or acted on' and lists example domains (financial verdicts, legal claims, medical lookups, public statements). It also advises preferring ask_pipeworx for casual lookups, providing clear when-to-use and when-to-avoid 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?

Extensive disclosure beyond annotations: fan-out behavior, response shapes, resolver logic, safety short-circuits, closed market handling, cancellation rules, wide spread tradeability. 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?

Very long and dense, covering many details. While well-structured with labeled sections, the verbosity may overwhelm an agent. Could be more concise without losing critical context.

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?

Thoroughly covers all aspects: resolver contract, parent event extractor, news fields, safety checks, cancellation rules. No output schema, but description explains return values 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?

Adds meaning beyond schema: explains market input can be slug, URL, or question; depth choices; include_raw effect. Schema coverage is 100%, but description enriches with examples and 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?

Clearly states it researches a Polymarket bet by pulling Pipeworx data. Distinguishes from siblings by focusing on bet-specific research with fan-out to category-specific data packs.

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

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

Explicit usage examples: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides category-specific fan-out examples. Lacks explicit when-not-to-use, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds value by disclosing that results are sorted by primary metric, return paired data plus citation URIs, and handle off-calendar fiscal years. 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 thorough and front-loaded with trigger phrases, but slightly verbose. However, each sentence serves a purpose (examples, data sources, return format). Almost every sentence adds value, so a slight deduction for density.

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

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

Given no output schema, the description adequately explains return values (paired data + citation URIs) and metric sorting. It covers entity types, data sources, and the number of inputs. For a union type with two distinct data sources, this is complete enough for proper agent 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%, but the description significantly enriches parameter meaning: it provides concrete examples (tickers for company, drug names), explains what data each type pulls (SEC EDGAR/XBRL vs FAERS), and notes special handling (off-calendar fiscal years). This is well 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 does side-by-side comparison of 2-5 companies or drugs in one parallel call, with example queries like 'Compare X and Y' and 'X vs Y'. It distinguishes from siblings by stating it replaces 8-15 sequential lookups, implying it's not for single-entity 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?

Explicitly provides example triggers (e.g., 'compare', 'versus', 'rank these companies') and states ALWAYS PREFER over sequential single-pack lookups. It defines scope (2-5 entities) and when to use for company vs drug types, with no ambiguity.

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 providing readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds significant behavioral context: returns findings packet with verbatim evidence, confidence, source, fetched_at, stable citation; explicit gaps[] for unanswered facets; never invents; expected 15-60s response; account requirement; extent of data sources. Goes well beyond annotations.

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

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

The description is appropriately sized for a complex tool. Critical information (account requirement, alternative tool) is front-loaded. It uses clear structure with bullet points for output and examples. Every sentence serves a purpose with no waste.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly explains return values (findings packet), error cases (empty gaps for non-structured topics), prerequisites (account), and time expectations. It covers all necessary context for an agent to use 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?

Schema coverage is 100% (both parameters described). The description adds meaning by explaining the 'depth' parameter's effect (quick=3, standard=5, thorough=8 facets) and that 'thorough' requires a paid plan. For 'question', it clarifies that broad/multi-part is fine. This adds value beyond the schema, leading to a score above the baseline of 3.

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

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

The description uses specific verbs and resources: 'grounded multi-source research across Pipeworx's 1127 STRUCTURED data sources' and 'decomposes your question into focused facets, routes each to the right one of 4,476 tools IN PARALLEL'. It clearly distinguishes from siblings like ask_pipeworx (single lookup) and provides context on when to use each.

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 (broad/multi-part questions over structured data) and when not to (single lookup use ask_pipeworx, breaking news prefer ask_pipeworx). Also includes prerequisites (account requirement) and alternative tool for non-signed-in users.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description's job is lightened. The description adds that the tool returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains the output behavior beyond annotations, but does not mention potential side effects like rate limits or auth, which is acceptable given 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?

Description is concise: three sentences, front-loaded with the main verb, no redundant phrases. Every sentence adds meaningful guidance.

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

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

Given the tool's complexity (discovering tools) and the rich annotations and schema, the description covers the output (what is returned), usage context (call first), and provides examples. It does not explain relevance ranking or behavior for empty queries, but these are minor omissions for a discovery tool. No output schema exists, so the description compensates by describing the return format.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by listing the domains of queries, explaining the aliases for the 'query' parameter, and providing concrete examples ('look up FDA drug approvals', 'analyze housing market trends'). This enhances understanding beyond the schema's 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 clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and explicitly distinguishes it from sibling tools by stating it is for discovering tools, not performing tasks. This is a specific verb+resource that stands out from siblings.

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist for:' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This directly tells the agent when to invoke this tool over 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 indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds substantial behavioral context: it describes the fan-out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), specifies the returned fields with details like sorting and URIs, and transparently discloses a known limitation ('USPTO PatentsView API sunset May 2025 — soft-fails until reactivated'). 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 well-structured: starts with attention-grabbing examples, states the primary use case and preference, then systematically details the sources, returned data, and input constraints. Every sentence earns its place, and crucial information is front-loaded. Despite length, it is efficient and scannable.

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

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

Given the tool's complexity (multiple data sources, conditional behavior, no output schema), the description is remarkably complete. It covers all return fields, explains fallback behavior (GDELT→GNews), notes limitations, and provides URIs format. No significant gaps remain for an agent to safely invoke the tool.

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

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

The input schema has 100% coverage with descriptions for both parameters. The description enriches this by clarifying that 'type' only supports 'company' (person/place 'coming soon'), that 'value' accepts ticker or zero-padded CIK but not names, and provides ample examples. This adds meaning beyond the schema definitions.

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

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

The description opens with numerous concrete examples ('Tell me about X', 'research Acme', etc.) that immediately convey the tool's purpose. It clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call' and distinguishes itself from sibling tools by advocating preference over chaining single-pack lookups. The purpose is specific, actionable, and well-differentiated.

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

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

The description explicitly states when to use the tool ('ALWAYS PREFER over chaining...when the user asks for a holistic view') and when not to use it ('names not supported — use resolve_entity first if you only have a name'). It provides clear context for tool selection and alternatives, leaving no ambiguity.

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 destructiveHint=true. Description adds context about when deletion is appropriate (stale, done, sensitive). No contradiction, but no additional behavioral traits beyond annotations.

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

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

Two concise sentences, front-loaded with purpose. Slightly redundant pairing mention could be trimmed, but overall 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?

For a simple deletion tool with one required parameter and no output schema, the description fully covers context and usage.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add extra meaning for the 'key' parameter beyond what the schema provides.

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

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

The description clearly states 'Delete a previously stored memory by key.' It uses a specific verb ('Delete') and resource ('memory by key'), and distinguishes from siblings 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: 'when context is stale, the task is done, or you want to clear sensitive data'. Also provides pairing guidance with 'remember and recall'.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds process details (fetches page, extracts title/description/key links, emits standard llms.txt format) 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 concise (3-4 sentences) with front-loaded purpose, followed by method and use cases. No redundant or irrelevant information.

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

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

Given the tool's low complexity, full schema coverage, and informative annotations, the description fully covers the tool's functionality, output, and use cases without needing additional 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?

Schema coverage is 100% with parameter descriptions. The tool description adds context about the output format and use cases, providing extra meaning beyond the schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb, resource, and context. It differentiates from siblings by focusing on file generation rather than AI visibility scanning.

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 use cases are provided (indexing client sites, drafting own project, auditing competitors). However, it does not mention when not to use it or directly contrast with sibling tools like ai_visibility_check.

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, etc. The description adds value by specifying what the schema includes (fields, geometry type, record count, capabilities), providing context 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?

Single sentence, front-loaded with the core action, no redundant words. Every part adds value.

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

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

For a simple schema retrieval tool with one parameter and no output schema, the description adequately covers what is returned. Could mention error handling or prerequisites, but minimal is sufficient.

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

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

Schema coverage is 100% with one parameter 'url' having a description. The tool description adds that the URL should be like '.../FeatureServer/0', providing additional formatting guidance 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 specifies the verb 'Get', the resource 'ArcGIS Feature/Map Service layer's schema', and lists the returned components (fields, geometry type, record count, capabilities). It distinguishes from sibling 'query_layer' which likely queries data rather than schema.

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

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

The description implies usage for schema retrieval by URL, and sibling 'query_layer' suggests an alternative for data queries. However, no explicit when-not-to-use or alternative mentions are provided.

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 value by specifying the exact fields returned (id, type, params, etc.), which is helpful since there is no output schema. No contradictions or missing disclosures.

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

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

The description is two sentences: first defines the action and output, second provides usage guidance. No redundant information, every sentence earns its place.

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

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

Given the simplicity of the tool (one optional param, no output schema), the description covers purpose, return format, and usage context. Annotations cover behavioral aspects. Nothing is missing.

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

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

Schema coverage is 100% with a clear description for the single optional parameter (include_inactive). The description does not add additional semantics beyond the schema, so 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 the verb ('List'), resource ('the caller's active subscriptions'), and scope ('active'). It also lists returned fields, distinguishing it from sibling tools like subscribe and unsubscribe which add or remove subscriptions.

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

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

The description explicitly says when to use it: 'to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and excludes 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 provide readOnlyHint=false and destructiveHint=false. The description adds context: 'Rate-limited to 5 per identifier per day. Free; doesn't count against your tool-call quota.' This discloses rate limits and quota impact, going beyond annotations. No contradiction.

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

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

5-6 sentences front-loaded with purpose, then use cases, then guidelines, then constraints. Every sentence earns its place. 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?

Tool has 3 params, 2 required, no output schema. Description covers all use cases, context structure, message formatting, rate limits, and quota. Complete for a feedback tool of this complexity.

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

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

Schema coverage is 100% (all params described). The description adds extra meaning: explains the 'type' enum in natural language, gives examples for 'context' (pack, tool, vertical), and specifies message length (2000 chars max). Adds value beyond 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 "Tell the Pipeworx team something is broken, missing, or needs to exist." It uses a specific verb (tell/send) and resource (Pipeworx team). It distinguishes from sibling tools like ask_pipeworx which are for queries, not feedback.

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 scenarios: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also includes guidelines like 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' No alternatives needed as this is the only feedback tool.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by explaining the data source ('CF analytics-engine'), privacy ('no PII'), and caching behavior ('5min-1h depending on window'). 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?

Three concise sentences with clear structure: main output, use cases, and data source/caching. Every sentence adds value without redundancy. Front-loaded with the primary result.

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 sufficiently explains the return structure (top tools, top packs, total call volume) and operational details (caching, data source). For a simple, single-parameter tool, this is complete.

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

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

The input schema already has 100% coverage with a description for the single parameter. The description does not add new semantic detail beyond what's in the schema. Baseline 3 is appropriate.

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

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

The description clearly states it returns 'top tools, top packs, and total call volume' over a specified window, using a specific verb ('returns') and resource ('what other AI agents are calling'). This is distinct from sibling tools like 'discover_tools' or 'search_datasets', as it focuses on real-time trending aggregated from agent usage.

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?

Three concrete use cases are provided: discovering hot data sources, confirming canonical tools, and checking alignment with common agent needs. While it doesn't explicitly state when not to use or name alternatives, the use cases are clear and contextually appropriate.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds rich behavioral context: the internal mechanics (monotonicity checks, partition-sum), semantic anchor (Jaccard similarity threshold), partition filter (placeholder slugs), fill check (theoretical vs realizable edge), and output format. 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 lengthy but well-structured with clear sections (requirements, modes, filters, response, fill check). It is front-loaded with the key requirement. Every sentence adds value, though some details could be slightly condensed without losing clarity.

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

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

Given the tool's complexity and lack of output schema, the description comprehensively explains the response structure (opportunities array with fields, partition_check details, fill check output). It also references sibling tool polymarket_fill_risk for custom sizing, ensuring completeness.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant value: explains that event accepts full URLs, topic is a seed question, and describes the behavior and mode-specific details. It goes well 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 that the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between single-event mode and cross-event mode, helping differentiate it from sibling tools like polymarket_edges and polymarket_fill_risk.

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 advises when to use event mode (for a specific market) vs topic mode (for cross-event scanning), mentions that calling with no arguments fails, and recommends polymarket_fill_risk for custom sizing. It provides clear context on usage and alternatives.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds significant behavioral details: caching (KV level, 1 hour, keyed on knobs), inclusion of diagnostics for empty segments, and that edge_pp_net is after slippage. 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 very long (approx. 500 words) and packs extensive detail, but it is not concise. It front-loads the main purpose but then dives into model families and response structure in dense prose. While well-structured with logical flow, it could be trimmed to improve 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?

Given the tool's complexity (9 parameters, multiple model families, detailed response structure), the description is highly comprehensive. It explains the output top-level fields (by_segment, diagnostics), the models, knobs, and even caching behavior. Since there is no output schema, the description fully compensates by detailing the return values.

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 each parameter having a description. The tool description adds contextual value by explaining parameter purposes in the broader tool workflow, such as slippage_pp referencing Polymarket fees and max_spread_pp for tight books. This goes beyond the schema's basic 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 verb 'scan' and resource 'Polymarket markets', specifying it returns opportunities where Pipeworx data disagrees with market price. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by emphasizing the 'what should I bet on today' use case and detailing internal model families.

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 extensive guidance on when to use this tool, including the purpose of discovering opportunities without paging hundreds of markets. It explains tradeable-edge knobs (min_liquidity, max_spread_pp) and mentions limitations like Fed bets being excluded from ranking due to data reliability. While it doesn't explicitly state when not to use it, the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: return structure (tracked, expired, snapshot_dates), constraints (60-day TTL, daily closes only, not intraday), and edge-case handling (gaps mean no scan). 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 appropriately sized and front-loaded with purpose. Every sentence adds value, and the structure is logical (overview, arguments, response details, limits). It may be slightly long but that is justified by the complexity.

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

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

Given no output schema, the description fully covers return values (tracked, expired, snapshot_dates) with all relevant fields and limitations. The tool has two optional parameters with 100% schema coverage. The description is complete and leaves no ambiguity.

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

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

Schema coverage is 100% with both parameters described. The description adds meaningful context beyond the schema: default values (14, '1wk'), clamp range for days (2-30), explanation that window refers to 'snapshot family'. This enriches the agent's understanding.

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

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

The description clearly states what the tool does: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots. Answers "how long has this edge existed and is it shrinking?"' This is a specific verb-resource combination (track persistence/decay) that distinguishes it from sibling tools like 'polymarket_edges' which presumably provides raw snapshots.

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

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

The description implies usage context (when you need to assess edge persistence) but does not explicitly state when to use or not use this tool versus alternatives. It provides clear context but lacks explicit exclusions or alternative tool references.

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, non-destructive. The description adds significant behavioral context: walks the order book ladder, returns a verdict (clean|degraded|cannot_fill), warns about forced directional risk and thin legs. 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 thorough but quite long and dense. It is structured with sections for single-market and basket, but the text is a wall of information that may be hard to parse quickly. Could be more concise while retaining key 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?

No output schema is provided, so the description must explain return values. It does so by listing key fields for both modes (e.g., top_of_book, slippage_pp, theoretical_sum, capture_ratio, forced_directional_risk). Covers most important aspects but could mention error handling or edge cases.

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

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

All 4 parameters have descriptions in the schema (100% coverage). The description adds extra meaning: explains the two modes, defaults, interpretation of size_usd (max spend vs target proceeds vs settlement notional), and clamping range. Enriches understanding beyond 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 it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes two modes (single-market and basket) and lists specific return fields. This differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly says 'REQUIRES one of market (single-market mode) or event (basket mode)'. Provides clear guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains the risks of partial fills and unhedged positions.

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 and idempotent behavior. The description adds extensive behavioral context: two operating modes, compatibility_warning conditions (bet shape mismatch, no overlap), temporal alignment info, and skipped counter details. This far exceeds what annotations provide.

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

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

The description is lengthy but well-structured with clear sections for modes, response, and safety fields. Every sentence provides necessary detail for a complex tool. Could be slightly more concise, but it balances completeness with organization.

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

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

Given the complexity of cross-venue spread analysis and the absence of an output schema, the description thoroughly explains all response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It covers caveats like temporal alignment and bet shape equivalence, ensuring the agent understands when spreads are meaningful.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining the relationship between topic and explicit parameters, listing specific topic values, and providing usage context (override behavior). This goes beyond the schema.

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

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

The description clearly identifies the tool as computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools by focusing on spread across two venues, unlike polymarket_arbitrage or polymarket_edges. The verb 'compute spread' and resource 'cross-venue' are specific.

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

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

The description explains two modes (topic shortcuts and explicit pairing) and provides examples. It warns that most pre-mapped topics yield compatibility warnings, guiding users on when results are meaningful. However, it does not explicitly compare with alternatives like polymarket_arbitrage or state when not to use this tool.

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

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

Description mentions returning attribute rows and geometry, adding to readOnlyHint and destructiveHint annotations. But no details on rate limits or authentication.

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 and a tip, front-loaded with main action. No superfluous content.

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

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

Given no output schema, description covers return type. But could specify format details or pagination behavior more explicitly.

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

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

All parameters are documented in schema with 100% coverage. Description adds context (SQL-like, comma-separated) and a helpful example for sampling ('1=1' + '*').

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

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

Clearly states the tool queries ArcGIS Feature/Map Service layers by URL. Distinguishes from sibling 'search_datasets' which finds datasets, making it a follow-up tool.

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

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

Provides a usage tip for sampling but does not explicitly state when to use this tool over alternatives like 'layer_info' or when not to use it.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds scoping to user identifier and listing behavior when key omitted, exceeding what annotations provide.

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

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

Three front-loaded sentences: core action, use case, auxiliary info. Every sentence adds value 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?

Covers retrieval behavior, listing, use case, scoping, and sibling relationships. Complete for a simple tool with one optional parameter and no output schema.

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

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

Schema coverage is 100% with one parameter described. Description adds usage hint to omit key to list all, enhancing meaning beyond 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 retrieves a value saved via remember or lists all keys if no argument is passed, with specific verb 'Retrieve' and resource 'saved values'. It distinguishes itself from siblings 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?

Explicitly says when to use it: to look up context stored earlier without re-deriving. Mentions pairing with remember and forget, providing clear alternatives and 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 indicate readOnlyHint=true, and the description adds important behavioral details such as the side effect of mark_read (flagging events read) and the persistence of the feed. This adds value 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 concise at three sentences, front-loaded with the core purpose, and efficiently covers return fields and parameter usage. Every sentence earns its place with no wasted words.

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

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

The description covers return fields, filtering, mark_read behavior, and alternative access. It is nearly complete for a read-only list tool, though it lacks explicit mention of ordering (implied most recent) and pagination details for the limit parameter. A 4 reflects minor gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds some context (e.g., example for type, explanation of mark_read) but does not significantly enhance parameter understanding beyond the schema. Hence, a 3.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifying the resource and action. However, it does not explicitly differentiate from sibling tools like list_subscriptions or subscribe, so a 4 is appropriate.

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 good usage context, noting that polling works fine and mentioning an alternative endpoint for scripts/dashboards. However, it lacks explicit when-not-to-use guidance or comparison with siblings, so a 4 is given.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds details: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail until reactivated, returns grouped changes with citation URIs. 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?

Description is detailed but well-structured with examples first, then sources, then parameter guidance, then sibling differentiation. Every sentence adds value; could be slightly more structured with bullet points but remains clear and efficient.

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

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

Given no output schema, description explains return shape (changes[] grouped by source + total_changes + citation URIs). Covers edge cases (USPTO soft-fail, GDELT→GNews fallback), parameter formats, and differentiates from sibling. Highly complete.

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

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

Schema coverage is 100% with descriptions. Description adds context: only 'company' supported for type, relative shorthand and recommended usage for since, ticker or CIK examples for value. Provides clear guidance beyond 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 provides a change feed for a company in the last N days/weeks/months via one parallel call, with example queries like 'What's new with X' and 'latest on Y'. It differentiates from sibling tool entity_profile for static profiles.

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

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

Explicitly tells when to use this tool vs entity_profile: 'Use entity_profile instead when you want the static profile... regardless of window.' Also recommends typical since values ('30d' or '1m') and explains fallback behavior between GDELT and GNews.

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

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

Description aligns with and complements annotations. Annotations indicate idempotentHint=true, not destructive; description explains persistence duration (authenticated: permanent, anonymous: 24h) and that it stores data, which is consistent with readOnlyHint=false.

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?

Concise, efficient description with no redundant information. Front-loaded with purpose, then usage guidance, then details. Every sentence serves a purpose.

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

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

Given the simple key-value store and full schema coverage, the description is complete. It covers scope, persistence, usage, and pairing with siblings. No missing information needed for correct invocation.

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

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

Schema covers 100% of parameters with descriptions. Description adds value by providing concrete examples for key (e.g., 'target_ticker') and explaining value can be any text, slightly enhancing 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: to save data for reuse across conversations/sessions. It specifies it stores key-value pairs scoped by agent identifier, and distinguishes from sibling tools recall and forget by mentioning them.

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 when-to-use guidance: when discovering something worth carrying forward (e.g., resolved ticker, address, preference). Mentions pairing with recall and forget, but does not explicitly state when not to use.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral context: 'Each call cascades through several lookup endpoints internally' and details about input acceptance (ticker, CIK, name). 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 somewhat lengthy but well-structured, starting with examples, then use case, then detailed type information. Every sentence adds value, though it could be slightly more concise.

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

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

Since there is no output schema, the description fully explains return values for both supported types. It also explains the internal cascading behavior. Given the tool's complexity and lack of output schema, the description is complete.

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

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

Schema description coverage is 100%, but the description adds significant meaning beyond schema by providing examples and specifying return values for each type (e.g., for company: ticker + CIK + company_name + citation URI; for drug: RxCUI + ingredient + brand + citation). This is extra value.

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

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

The description clearly states the tool's purpose: resolving a user-spoken name to a canonical/official identifier. It provides specific examples and lists supported entity types (company, drug) with details, distinguishing it from sibling tools by stating 'Use FIRST whenever you have a name but need an ID.'

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 when to use the tool ('Use FIRST whenever you have a name but need an ID') and mentions that it replaces multiple manual lookups. It does not explicitly state when not to use it or list alternatives, but the context is clear enough.

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 safe, idempotent, non-destructive behavior. The description adds value by explaining the probing process ('probes each entity with ai_visibility_check'), ranking, and output structure (score, confidence, signal density). 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?

Five sentences front-load the main purpose and provide necessary details without excess. Every sentence adds value: purpose, method, use case, output description, and optional parameters. 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?

Given no output schema and moderate parameter count (4), the description adequately explains the tool's behavior and output (ranked list with metrics). However, it could be more explicit about error handling or edge cases. Still, it provides sufficient context for correct invocation.

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

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

Schema coverage is 100%, providing baseline 3. Description enhances meaning by explaining that entities[0] is the subject, models array supports specific values (workers-ai, anthropic), and _apiKey is conditional. Adds context beyond 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: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (scan/compare), resource (competitor AI presence), and differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (generic).

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

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

Provides explicit when-to-use guidance: 'Useful for competitive AI-marketing audits: does Claude know about us as well as our competitors?' It implies the use case of comparing multiple entities, but does not explicitly state when not to use or list alternatives beyond mentioning ai_visibility_check.

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

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

Adds behavioral context beyond annotations: mentions partial failure handling, 5-30s timeout for first measurement, and that sources_failed will list timed-out sources. No contradiction with annotations.

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

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

Description is dense but well-structured: front-loads purpose, then usage guidance, then behavioral details. Slightly long but each sentence adds value.

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

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

Given complexity (composite tool, no output schema), description is highly complete: lists return fields (summary block, advisories, links, alternative versions), source behavior, and failure modes.

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

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

Schema coverage is 100%, so baseline 3. Description adds minor value by clarifying scoped packages for 'package' and default behavior for 'version', but schema already describes them adequately.

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

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

Description clearly states it's a composite check for npm packages covering license, advisories, bundle size, etc. Distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on dependency evaluation.

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

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

Explicitly says when to use ('is X safe / popular / small') and when not to (non-NPM ecosystems should use deps.dev:version directly). Provides clear alternative guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the exact fields returned and the intended workflow, 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?

Two short sentences: the first defines action and domain, the second specifies output and further use. Efficiently front-loads key 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?

Despite no output schema, the description fully explains the return structure and its purpose. It covers how to use the results with sibling tools, making it complete for a search/discovery 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% with descriptions, but the description enriches by giving concrete keyword examples (parcels, crime, flood zones) and clarifying that org_id overrides the default, providing context 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 it searches City of McKinney GIS datasets by keyword and lists what is returned. It distinguishes from sibling tools like query_layer and layer_info by specifying that the returned URL can be passed to them.

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 next-step guidance: pass the returned URL to query_layer or layer_info. While it doesn't state when not to use the tool, the chaining instruction is valuable.

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

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

Adds details beyond annotations: describes use of BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging, and output includes offsets for verification. 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?

Concise at ~120 words, well-structured with clear sentences covering purpose, usage, mechanics, and limitations. Every sentence contributes useful 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?

Despite no output schema, description fully explains return value (top-N passages with offsets and scores) and behavior on truncation. Complete for the tool's complexity.

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

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

Schema has 100% description coverage; description adds value with examples for query, default for limit, and char limit for text. Enhances understanding beyond schema.

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

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

Clearly states 'Semantic search INSIDE a fetched record' and explains the action: passing text and query to get top-N passages. Distinguishes itself by emphasizing it operates on already-fetched records, which is unique among siblings.

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

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

Explicitly advises use when records are too large for prompts, saving context. Also pairs with ask_pipeworx_grounded for grounding, providing clear alternative workflow.

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

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

Annotations indicate a write operation (readOnlyHint: false), idempotent (idempotentHint: true), and non-destructive (destructiveHint: false). The description adds behavioral context: OAuth requirement, type-specific filtering, delivery channel restrictions, and webhook signing secret handling. 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 appropriately sized for the tool's complexity, with a clear front-loaded purpose sentence followed by organized sections on requirements, types, and delivery. Every sentence adds useful information 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?

Given no output schema, the description mentions the return value (new subscription id). It covers all parameters, requirements, type-specific filters, delivery channels, and limitations. The description is complete for an agent to correctly invoke the tool.

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

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

With 100% schema coverage, the description adds significant value beyond the schema by providing concrete examples, code snippets, and detailed explanations for type-specific parameters and delivery options (e.g., 'sec_8k: items:["5.02"] = officer change').

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. The verb 'Create' and resource 'subscription' are unambiguous, and the description differentiates from sibling tools (list_subscriptions, unsubscribe) by focusing on creation.

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 specifies when to use: requires a Pipeworx OAuth account (anonymous/BYO cannot persist). It provides detailed guidance on supported types, parameters, and delivery channels, including limitations (SMS cap, webhook auto-disable). However, it does not explicitly contrast with sibling tools like list_subscriptions or unsubscribe.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral context: it is the onboarding entry point, produces live catalog examples, and explains return structure. 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?

Front-loaded with common queries, then describes output and usage. Every sentence is informative, though slightly long. Dense with value, no wasted words. Score reflects strong structure but slight verbosity.

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

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

No output schema, but description fully explains return type: category-bucketed example questions with tool+argument shapes. Covers onboarding context, argument semantics, and intended first-use scenario. Complete for a discovery 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 describes 'topic' with optional focus areas; description adds that omitting it gives full spread and passing it focuses. This adds meaning beyond schema. Schema coverage is 100%, so baseline is 3, and description earns a 4 for the extra context.

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

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

The description clearly states the tool returns category-bucketed example questions with exact tool+argument shapes. It distinguishes from siblings like ask_pipeworx and discover_tools by positioning itself as the onboarding entry point. The verb 'returns' and resource definition are specific.

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

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

Explicitly states when to use: 'FIRST when you do not yet know what Pipeworx can do' or to learn meta-tool calls. Provides usage context: call without arguments for full spread, or pass topic to focus. Implicitly contrasts with alternative meta-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?

The description adds key behavioral context beyond annotations: the row is deactivated not deleted, preserving history. Annotations already indicate non-destructive write and idempotency.

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 verb and constraint, no wasted words.

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

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

Given the simple tool (1 param, no output schema, good annotations), the description covers purpose, ownership, and retention behavior completely.

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% (single parameter 'id' with clear description). The description only adds that the id comes from subscribe, which is implicit in 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 'Cancel a subscription by id' and distinguishes from sibling tools like subscribe and list_subscriptions by specifying ownership enforcement and the deactivation behavior.

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

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

The description specifies that only own subscriptions can be canceled and references recent_alerts for historical events, providing context for when to use this tool.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds significant behavioral context: it returns a verdict with specific types, structured form, actual value with citation, and percent delta. It also notes that it replaces multiple sequential calls, providing transparency about its efficiency advantage.

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 approximately 4 sentences, front-loaded with example queries, and contains no redundant or unnecessary words. Every sentence adds value: purpose, usage context, domain, return structure, and efficiency claim.

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 single input parameter with full schema coverage, and no output schema, the description adequately explains the return format (verdict types, citation, delta). No additional information is needed for an agent to correctly invoke the tool and interpret results.

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

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

The schema has 100% description coverage for the single parameter 'claim', with clear examples. The tool description does not add additional semantic information beyond the schema. 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 natural language examples and explicitly states the tool's purpose: natural-language claim verification against authoritative sources, specifically company-financial claims for public US companies via SEC EDGAR + XBRL. This clearly distinguishes it from sibling tools, none of which perform claim verification.

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 specifies when to use the tool ('whenever the agent needs to check whether something a user said is factually correct') and the supported domain (company-financial claims). While it does not explicitly list when not to use it or provide alternatives among siblings, the domain restriction implicitly guides usage.

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