Arcgis Hub

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds that it returns per-model detail (score, confidence, signals, raw_response) plus combined view, and explains the API key pass-through. 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?

Two sentences, directly to the point: purpose, default, optional key, return structure, use cases. 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?

No output schema, but description explains return shape per-model and combined. Covers key behavior and parameters adequately for a probing tool. Missing details on scoring methodology but not critical.

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 by explaining default model for 'models', optional key relevance, and context usage for disambiguation. Exceeds 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?

Description clearly states it probes LLMs for knowledge about an entity and scores visibility (0-100). Verbs 'probe' and 'score' specify the action and resource. However, it does not differentiate from sibling 'scan_competitor_ai_presence' which may overlap in purpose.

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

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

Explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Implies when to use but does not state when not to use or provide alternatives. The default model and BYO key option are 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, destructiveHint=false. Description adds valuable behavioral context: it routes to one of 4,476 tools across 1,127 sources, fills arguments, and returns stable pipeworx:// 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?

The description is long but front-loaded with the core purpose and usage guidance. Every sentence adds value—examples, alternatives, edge cases. Could be slightly tighter but remains efficient for its richness.

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 (4,476 tools, many sources), the description covers purpose, usage guidelines, examples, and notes about output (structured answer with citation URIs). No output schema exists, but the description adequately describes 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 coverage is 100%; the input schema already documents all 6 parameters as aliases for 'question'. The description merely repeats that it accepts query, q, prompt, text, input as aliases, adding no new semantic 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 resolves factual questions about structured data, using specific verbs like 'ask', 'routes', 'returns'. It distinguishes from siblings by naming ask_pipeworx_grounded and deep_research, and provides extensive examples.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and gives concrete when-to-use criteria (user asks 'what is', 'look up', etc.). Also tells when to step up to alternatives: ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions.

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, idempotentHint, etc.), the description explains the routing process, that it uses ONLY the tool result, the return structure with evidence and refusal reasons, and the cost tradeoff. 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 lengthy but front-loaded with the core purpose. It has a clear structure and each sentence adds value. Slightly verbose but appropriate for the tool's complexity.

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

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

Given no output schema, the description fully explains the return structure (answer, evidence, confidence, source, etc.) and refusal reasons. It covers routing, how the tool works, and use cases, leaving no significant gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no additional meaning beyond the schema's parameter descriptions. It mentions 'fills arguments' but does not elaborate on syntax or format.

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 is a hallucination-resistant answer mode for high-stakes reads. It distinguishes from ask_pipeworx by noting the extra LLM call and the return of evidence and refusals. Specific use cases (financial, legal, medical) are given, and it mentions routing to 4476 tools across 1127 sources.

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 answer will be quoted, cited, or acted on, and must not invent facts) and when to prefer ask_pipeworx (casual lookups). Provides clear examples of high-stakes domains, giving both positive and negative guidance.

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

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

The description thoroughly discloses internal behavior: classifier and fan-out examples, resolver contract with match confidence, parent event extraction, news fallback mechanism, safety short-circuits for low-confidence and closed markets, and resolution-rule risk. Annotations already confirm read-only and idempotent, and description adds significant context without contradiction.

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

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

The description is quite long (multiple paragraphs) but well-organized with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and front-loaded with core purpose. However, given the complexity, some redundancy could be trimmed for better 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?

No output schema exists, so the description fully compensates by detailing response shapes (market, analysis, evidence), resolver fields, parent event extraction, news metadata, and safety mechanisms. It covers all necessary edge cases and behavioral nuances.

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

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

Schema coverage is 100%, and the description adds value by providing examples for 'market', explaining 'depth' with 'quick vs thorough' semantics, and detailing 'include_raw' benefits. 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 explicitly states the tool researches Polymarket bets by pulling Pipeworx data, accepts various input forms (slug, URL, question), and produces evidence packets and market-vs-model comparisons. It clearly distinguishes from sibling tools like polymarket_edges or polymarket_arbitrage by being the general research tool.

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

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

The description provides explicit use cases (e.g., 'should I bet on X'), explains how to invoke with examples, and warns about resolution confidence, closed markets, and wide spreads. It lacks explicit when-not-to-use or direct sibling comparisons but gives enough context for appropriate invocation.

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

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

The description discloses that for companies it pulls latest 10-K financials from SEC EDGAR/XBRL with correct handling of off-calendar fiscal years, and for drugs it pulls FAERS adverse-event counts, FDA approvals, and trial counts. It also mentions sorting by primary metric and citation URIs. Annotations already indicate read-only and idempotent, so this adds behavioral context 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 front-loaded with common user queries, then gives a clear rule to prefer this tool, then details per type. Every sentence adds value; no redundancy. It is well-structured and appropriately sized for the complexity.

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

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

The description covers key aspects: what data is pulled, how it's sorted, and that it returns paired data with citation URIs. However, it could be slightly more specific about the exact output structure, but given the tool's read-only nature and no output schema, it is largely complete.

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

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

Schema coverage is 100% and parameters are well described, but the description adds crucial context: it explains that 'values' must be 2–5 tickers/CIKs for company or drug names, and provides examples. This adds meaning beyond the schema alone.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call, using specific verbs like 'compare' and 'rank'. It distinguishes itself from siblings by emphasizing it should be preferred over sequential single-pack lookups.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and notes it replaces 8–15 sequential lookups, providing clear guidance on when to use this tool versus alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent. Description adds critical context: requires account (free via GitHub), time estimate 15-60s, not open-web search, returns gaps[] when data cannot answer, and that 'thorough' depth is paid. 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: critical info (account, alternatives) at beginning, then process, then examples, then limitations. Every sentence adds value, but could be slightly tighter without losing information.

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

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

Given the tool's complexity (2 params, no output schema), the description is comprehensive. It explains the research process, output format (findings packet with evidence, confidence, source, fetched_at, citation, gaps), limitations, when to use alternatives, and expected latency. No output schema so this detail is necessary and provided.

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 both parameters with descriptions. Description adds value by explaining the depth enum values (quick=3, standard=5, thorough=8) which are not in the schema. However, schema already provides the enum options, so the addition is helpful but not essential.

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 grounded multi-source research across Pipeworx's structured data sources, decomposing questions into facets and routing to tools in parallel. It distinguishes from sibling ask_pipeworx by specifying that deep_research is for broad/multi-part questions over structured data, while ask_pipeworx is for single lookups or breaking news.

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 this tool vs alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. Also notes account requirements and that 'thorough' depth needs a paid plan. Provides example questions that are 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it 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,' which is valuable behavioral context beyond the annotations.

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

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

The description is a single dense paragraph that front-loads the purpose. It is concise with no wasted words, though slight restructuring into bullet points could improve scanability. Still, it earns its keep.

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 adequately explains what the tool returns: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It covers when to use and what the input is, making it complete for its purpose. Lacks mention of error handling or edge cases, but not critical.

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

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

Schema coverage is 100%, and the description provides context for the main 'query' parameter (natural language description) and lists aliases. While the schema already describes the parameters, the description reinforces usage with examples and explains the purpose of the aliases, adding value over the schema alone.

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 'Find tools by describing the data or task' and lists many domains. It distinguishes itself from siblings by positioning it as a meta-tool for exploring the toolset, with the directive 'Call this FIRST when you have many tools available.' This makes its purpose specific and distinct.

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

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

Explicitly says 'Use 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.' This provides strong contextual guidance, though it does not explicitly list when not to use or enumerate alternatives.

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

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

The description adds significant behavioral context beyond annotations: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), specifies return fields, mentions parallel execution, and discloses the USPTO soft-fail condition. Annotations already convey safety, idempotency, and open-world behavior, but the description enriches this with operational details.

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 relatively long but efficiently structured: it opens with real user queries, then states the core value proposition, lists sources, and details outputs. Every sentence adds value, though a slight trim could improve conciseness 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 complexity (multiple data sources, parallel fan-out) and the absence of an output schema, the description thoroughly explains what the tool returns (cik, filings with URIs, fundamentals, patents, news, LEI) and notes limitations (USPTO soft-fail). It leaves little ambiguity about the tool's capabilities.

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

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

Schema description coverage is 100%, so the baseline is 3. The top-level description reiterates the same param info (e.g., ticker or CIK, names not supported) already present in the schema descriptions. No substantial new parameter meaning is added 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 the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call'. It provides specific verbs ('Tell me about', 'research', 'brief me on') and distinguishes from siblings by explicitly preferring over chaining single-pack lookups and referencing sibling tools like resolve_entity for name resolution.

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

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

The description gives explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. It also states when not to use: 'names not supported (use resolve_entity first if you only have a name)', providing a clear alternative.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about use cases (stale, done, sensitive data) but does not significantly expand on behavioral traits beyond what annotations provide.

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

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

The description is two sentences, front-loaded with the primary purpose, and contains zero redundant words. Every sentence adds value.

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

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

The tool is simple (one parameter, no output schema). The description covers purpose, when to use, and pairs with related tools. No missing information given the 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% and the schema already describes 'key' as 'Memory key to delete'. The description does not add additional meaning beyond the schema, so baseline score of 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 explicitly states the action ('Delete') and the resource ('a previously stored memory by key.'). It distinguishes from siblings by naming '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?

The description provides clear when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' It does not explicitly contrast with alternatives but implies pairing 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral details: fetches page, extracts title/description/key links, emits standard markdown format, output as single text blob. 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?

Concise and front-loaded with the core action and output. Could be slightly tighter, but no wasted sentences.

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?

Adequately covers purpose, usage, output format, and behavioral context. Lacks error handling or limitations, but given simplicity and thorough annotations, completeness is good.

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

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

Schema coverage is 100%, and the description does not add new parameter info beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the format and use cases (indexing by AI crawlers). No sibling tool overlaps with this purpose.

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

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

Provides explicit use cases: getting client's site indexed, drafting own llms.txt, auditing competitor AI visibility. Lacks explicit 'when not to use', but scenarios are 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 as true and destructiveHint as false. Description adds value by specifying exactly what schema information is returned (fields, geometry, count, capabilities), reinforcing that it is a safe, read-only operation.

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 key verb and resource, no waste. Efficiently conveys purpose and output.

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

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

Given the single parameter, comprehensive annotations, and lack of output schema, the description fully covers what the tool returns (fields, geometry, count, capabilities). No gaps for expected 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% with a clear description and example for the 'url' parameter. The tool description does not add additional semantics beyond what is already in 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?

Description clearly states the verb 'Get' and the resource 'ArcGIS Feature/Map Service layer's schema', listing specific items returned (fields, geometry type, count, capabilities). Distinguishes itself from sibling 'query_layer' which likely queries data, not 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?

Description clearly indicates the tool is for getting schema by URL, with an example format. It implies use for schema retrieval, but does not explicitly state when not to use or mention alternatives like 'query_layer' for data queries.

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

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

Annotations already declare read-only and non-destructive behavior. The description adds value by listing the return fields and clarifying the scope (caller's subscriptions), which aligns with annotations perfectly.

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

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

Two sentences, front-loaded with purpose, then return fields, then usage guidance. 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?

For a simple list tool with full annotation coverage and a single documented parameter, the description provides all necessary information, including return fields and usage intent.

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 the single parameter (include_inactive) with description. Description adds no additional meaning beyond the schema. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description clearly states it lists the caller's active subscriptions, specifies the return fields, and distinguishes from sibling tools like subscribe/unsubscribe.

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

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

Provides explicit use cases: review what you're monitoring before adding more or find an id to cancel. Does not explicitly mention when not to use it, but usage 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?

Discloses rate limit (5 per identifier per day), that feedback is free and doesn't count against tool-call quota, and that the team reads digests daily. These details go well beyond the annotations (which only indicate readOnlyHint=false, etc.).

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

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

The description is front-loaded with the purpose, then provides usage categories, tips, and limitations. Every sentence adds value, and it is appropriately sized for the tool's simplicity.

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 all necessary aspects: purpose, when to use, input format (including what to avoid), rate limits, and cost. For a simple feedback tool with no output schema, this is fully 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 clear descriptions for each parameter (type enum, context object, message). The description adds nuance (e.g., don't paste user prompt) but does not significantly expand parameter 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 is for providing feedback about broken, missing, or needed tools/data. It uses specific verbs ('tell', 'is broken/don't exist') and distinguishes itself from sibling tools which are primarily query or research tools.

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

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

Explicitly describes when to use (bug, feature, data_gap, praise) and includes a tip to describe in terms of Pipeworx tools rather than pasting end-user prompts. No explicit 'when not to use' but the sibling list shows no other feedback tool, so exclusions are implied.

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, idempotentHint, and non-destructive behavior. The description adds valuable context: data source (CF analytics-engine), privacy (no PII), and caching window (5min-1h). 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 well-structured with a clear statement, use cases, and technical notes. It could be slightly more concise, 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 no output schema, the description mentions return content (top tools, packs, volume) but lacks precise structure or formatting. Caching and data source details are good. Overall sufficient for a straightforward analytics 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 a clear description of the 'window' parameter. The description adds interpretative value by explaining that shorter windows show hot trends while longer windows show steady-state demand.

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 top tools, top packs, and total call volume over a window. It differentiates from sibling tools like ask_pipeworx and discover_tools by focusing on aggregate trending data.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming canonical tool, aligning use case). It does not explicitly state when not to use, but the context implies it is for aggregate trending, not individual queries.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by detailing the internal logic: monotonicity checks, partition_sum computations, Jaccard similarity threshold (≥0.30), placeholder filtering (dropping will-person-X slugs, >20% placeholder fraction returns null), fill check behavior (realizable_edge_pp ≤ 0 means no trade), and that skipped_low_similarity surfaces rejected pair count. This fully discloses behavioral traits.

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

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

The description is comprehensive but somewhat verbose (multiple paragraphs). It front-loads the requirement and explains modes, but includes some repetition (e.g., partition check details appear in both mode descriptions). Given the tool's complexity, the length is justified, but could be slightly more streamlined.

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

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

Given the absence of an output schema, the description adequately details the response structure (opportunities[], partition_check object, fill check info) and references a sibling tool (polymarket_fill_risk) for custom sizing. It covers both modes, the semantic anchor, partition filter, and fill check, leaving no major gaps for an agent to understand usage and output.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining the purpose of each parameter, providing concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), and noting that full Polymarket URLs are also accepted for event. This enriches the schema descriptions.

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

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

The description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks, distinguishing between single-event mode (event parameter) and cross-event mode (topic parameter). It uses specific verbs like 'Find', 'walks', 'computes' and specifies the resource (Polymarket event markets). Sibling tools like polymarket_edges and polymarket_fill_risk are not directly compared, but the purpose is distinct and unambiguous.

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

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

The description explicitly recommends event mode for specific markets and topic for cross-event scanning, noting that cross-event catches patterns missed by single-event. It warns that calling with no args fails and provides guidance on subsequent actions: when partition signal fires, use fill_check; for custom sizing, use polymarket_fill_risk. It lacks explicit 'when not to use' but gives strong contextual cues.

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 etc., so the safety profile is already clear. The description adds substantial behavioral context: explains three model families, the math behind each (lognormal barrier, GDELT momentum, partition_overround with corrections), tradeable-edge knobs, response structure including diagnostics, and caching at KV level for 1 hour. This goes far beyond what annotations provide.

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

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

While well-structured with clear sections (purpose, segments, knobs, response), the description is quite long and verbose. It could be tightened without losing key information, such as combining similar details. An AI agent might need to parse through a lot of text to extract the core constraints.

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 has 9 parameters and no output schema, the description is highly complete. It covers all segments, their edge calculations, tradeable-edge filters, response structure including diagnostics, and caching. No missing 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?

All 9 parameters have schema descriptions (100% coverage), but the description adds significant context: explains how min_partition_leg_kelly differs from min_kelly, describes 'Tradeable-edge filter' for max_spread_pp and min_liquidity, and mentions caching keyed on all knobs. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is built for discovering betting opportunities without manual paging. The specific models and segments are detailed, distinguishing it from siblings like polymarket_arbitrage or polymarket_edge_tracker by focusing on Pipeworx-driven edge detection.

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 it's for 'what should I bet on today' and explains the tradeable-edge knobs (min_liquidity, max_spread_pp) and when to adjust them. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage, leaving some ambiguity about when to prefer this tool over others. Still, the usage 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 readOnly, idempotent, and non-destructive. The description adds significant context beyond that: data limitations (60-day TTL, snapshot start date), source of decay numbers (daily closes of edge_pp_net, not intraday), and response structure. 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 a single, information-dense paragraph. It front-loads the core purpose and then provides necessary technical details. Every sentence adds value, but the structure could be improved with bullet points or clearer separation of sections for easier scanning.

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

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

Given the tool has no output schema, the description thoroughly explains the response (tracked, expired, snapshot_dates arrays) and key behavioral aspects (lifespan median, data gaps). It covers limitations and data provenance, making the tool self-contained for a read-only query.

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 supplements this by providing default values (14 days, '1wk' window) and a max constraint (30 days for days), which adds practical 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 states the tool provides 'Edge persistence and decay telemetry' from daily snapshots, answering how long an edge has existed and whether it is shrinking. This is a specific verb-resource pair that distinguishes it from sibling tools like polymarket_edges (which likely provides current edges) and polymarket_arbitrage (arbitrage opportunities).

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 by contrasting fresh vs. old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'), indicating when decay analysis is critical. However, it lacks an explicit 'when to use' or 'when not to use' directive or direct comparison to siblings, leaving some inference needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds rich behavioral detail: walks the CLOB ladder, computes slippage, provides a verdict (clean|degraded|cannot_fill), and for baskets identifies thin legs and forced directional risk. No contradiction with annotations.

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

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

The description is dense but well-structured: starts with one-line purpose, then required parameters in caps, then separate paragraphs for single-market and basket modes, each listing return fields. Every sentence adds essential information. No fluff.

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

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

Despite no output schema, the description fully enumerates all return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, capture_ratio, thin_legs). It also explains use cases and risks. Given tool complexity, this is completely adequate.

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 4 parameters. The description greatly extends meaning: explains how size_usd differs between modes ('max spend on buys, target proceeds on sells' vs 'settlement notional'), details default side logic for baskets, and reveals that returns include detailed fill metrics and risk flags.

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 precisely states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket) with specific return fields. This clearly 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 advises 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and warns that 'partial basket fills convert an arb into an unhedged directional position'. Provides when-to-use and when-not-to-use guidance.

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

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

Discloses behavior beyond annotations: two modes, safety fields (compatibility_warning, temporal_alignment), skipped cross-type/subtype counters, and validity conditions for spreads. 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?

Comprehensive but verbose (~200 words). Well-structured with logical flow, but could be more concise for agent parsing.

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 input modes, response fields, edge cases, and safety conditions. Lacks output schema but description compensates; fairly complete for a complex tool.

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

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

Schema coverage is 100% with good descriptions; description adds value by explaining mode interaction and providing examples, moderately beyond the baseline.

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

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

Description clearly states it computes cross-venue spreads between Kalshi and Polymarket for the same question, with two modes (topic shortcuts and explicit pairings). This distinguishes it from sibling tools like polymarket_arbitrage (intra-venue).

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?

Explains two modes and offers caution about pre-mapped topics returning warnings, but does not explicitly compare to alternatives like polymarket_arbitrage or 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?

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds that it returns attribute rows and geometry, which provides behavioral context beyond annotations. 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?

Two sentences plus a short tip. Every sentence is informative and front-loaded with purpose. 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?

Covers the query functionality, parameter usage, and return type (attribute rows and geometry). Lacks details on error handling and pagination beyond offset, but the open-world annotation compensates. Adequate for a query 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%, so baseline is 3. Description adds context like 'SQL-like where' and the sampling tip, which adds meaning beyond the schema descriptions. However, it does not provide new format syntax for parameters not already in 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 queries an ArcGIS Feature/Map Service layer by URL, listing the supported SQL-like parameters. It distinguishes from siblings like search_datasets and layer_info by specifying the querying function.

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

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

Provides a usage tip for sampling data ('where="1=1" + out_fields="*"'), giving clear context. While it doesn't explicitly state when not to use or name alternatives, the context signals imply it follows a dataset search, making guidance adequate.

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 behavioral context about scoping to the user's identifier (anonymous IP, BYO key hash, or account ID), which goes beyond annotations and helps the agent understand data isolation.

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 deliver all necessary information. The first sentence immediately states the action and alternatives, followed by usage context and scope. 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?

For a simple tool with one optional parameter, rich annotations, and no output schema, the description covers purpose, usage, scope, and related tools completely. Nothing critical is missing.

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

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

The one parameter 'key' is fully documented in the schema (100% coverage). The description adds meaning by explaining the dual behavior: providing a key retrieves its value, omitting it lists all keys. This clarifies the parameter's effect beyond the schema's description.

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

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

The description explicitly states the tool's two functions: retrieve a specific value by key or list all saved keys. It uses specific verb-resource pairs ('Retrieve... via remember', 'list all saved keys') and distinguishes clearly from sibling tools like 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?

The description provides solid usage guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also recommends pairing with remember and forget. However, it does not explicitly state when to avoid this tool in favor of alternatives, though the context is clear.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive. The description adds behavioral detail about 'mark_read' flagging events as read, and notes that the same feed is available via a GET endpoint, providing useful context 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 concise, with four sentences that each add essential information. It front-loads the purpose and is well-structured, avoiding redundancy or fluff.

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

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

The description covers key return fields, acceptable usage (polling), and an alternative access method. Although there is no output schema, the description sufficiently explains what to expect. It could be more complete by noting pagination or error handling, but overall it is adequate for the tool's simplicity.

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 clear descriptions for each parameter. The description adds value by summarizing filtering options (by type and since) and explaining the effect of mark_read, enhancing understanding beyond the schema alone.

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 'Pull fired events from your subscription feed,' specifying the action and resource. It also lists the key return fields (source, citation_uri, raw event payload), making the tool's purpose unambiguous.

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

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

The description mentions polling is fine and provides an alternative REST endpoint, giving context for appropriate use. However, it does not explicitly compare to sibling tools like 'list_subscriptions' or specify 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?

Beyond annotations (readOnlyHint, idempotentHint), the description discloses the fan-out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO with sunset caveat) and the return structure (changes grouped by source, total_changes, citation URIs). No contradictions with annotations (readOnlyHint aligns with read-only operation).

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

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

The description is well-structured and front-loaded with example queries. It is relatively long but each sentence adds value: examples, fan-out details, parameter formats, and alternative tool reference. Could be slightly more concise but is not overly verbose.

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

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

For a complex tool with multiple data sources, fallbacks, and parameter formats, the description provides complete guidance. It covers return structure, parameter constraints, and alternative tools. No output schema exists, but the description compensates by describing the output format. The tool's complexity warrants this 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 description coverage is 100% (baseline 3), but the description adds significant context: it explains the 'since' parameter accepts ISO dates or relative shorthand with examples ('7d', '30d', '3m', '1y'), and the 'value' parameter can be a ticker or CIK with specific examples. This goes beyond schema descriptions.

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

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

The description starts with example queries ('What's new with X', 'latest on Y') that clearly indicate the tool's purpose: providing a change feed for a company over a time window. It explicitly differentiates from the sibling tool 'entity_profile' by stating when to use that alternative instead, fulfilling the verb+resource+distinction requirement.

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 examples (e.g., 'What's new with X', 'updates on Acme') and when-not-to-use by recommending 'entity_profile' for static profiles. It also implies alternatives by naming the sibling tool, meeting the highest standard for usage guidance.

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

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

Adds context beyond annotations: persistence differences (authenticated vs. anonymous), key-value scoping. Missing explicit overwrite behavior, but overall informative.

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?

Informative with multiple sentences; front-loaded purpose. Could be slightly more concise 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 simple tool with complete schema and annotations, description covers purpose, usage, and behavioral context comprehensively.

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

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

Schema covers both key and value with examples; description doesn't add semantic detail beyond schema, so baseline 3 is appropriate.

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

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

Description clearly states the tool saves data for reuse across conversations/sessions, with specific examples. Distinguishes from sibling tools recall and forget.

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

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

Explicitly tells when to use ('discover something worth carrying forward') and mentions alternatives: recall to retrieve, forget to delete.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: internal cascading through multiple lookup endpoints, replacing 2-3 manual lookups. It also details return values for each type (ticker, CIK, RxCUI, citation URIs), which goes 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 moderately long but well-structured: starts with example queries, states purpose, gives usage guidance, then details supported types. Every sentence adds value, but it could be slightly more concise 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 (two entity types, multiple input formats, internal cascading), the description is complete. It explains return values without an output schema, covers use cases, and mentions citation URIs. No gaps are apparent.

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

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

Schema coverage is 100%, but the description adds significant meaning: accepted formats for 'value' (ticker, CIK, name for company; brand/generic for drug) and examples. This helps the agent understand valid inputs beyond the schema's brief 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: resolving a user-spoken name to a canonical identifier. It provides specific examples (ticker, CIK, RxCUI) and distinguishes itself from siblings by being the go-to for name-to-ID conversion, as implied by '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 gives explicit guidance to use this tool 'FIRST' when needing an ID from a name. It includes example queries that illustrate typical use cases. However, it does not explicitly mention when not to use it or list alternatives, though the sibling list implies other tools are for post-ID tasks.

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

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint true, and destructiveHint false. The description adds context: it probes each entity with ai_visibility_check, outputs a ranked list with score/confidence/signal density, and mentions the models parameter and optional API key. No contradictions with annotations.

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

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

Four sentences, front-loaded with the core action. Each sentence adds necessary information: purpose, method, use-case, output format. No redundant or extraneous content. Highly 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 4 parameters (including optional API key), the description covers the tool's behavior well. It explains the process (probe, rank, surface) and return format (ranked list with metrics). No output schema exists, but the description compensates by describing the output. Could mention more about error handling or rate limits, but overall 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 each parameter having a description. The description adds minor value by noting the first entity is treated as the 'subject' and the default model is 'workers-ai' if omitted. However, most parameter context is already in the schema, so the description provides only modest additional semantic 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 uses a specific verb-resource pair ('Compare AI visibility across multiple entities side-by-side') and clearly distinguishes this tool from its siblings. It explicitly mentions it probes entities with ai_visibility_check, ranks them, and surfaces most/least recognized, with a concrete example question. This differentiates it from similar tools like compare_entities or ai_visibility_check.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question. However, it does not explicitly state when not to use this tool or mention alternatives (e.g., for a single entity use ai_visibility_check). The guidance is good but could be more precise about exclusions.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds beyond annotations: explains graceful degradation, timeout behavior for bundlephobia (5-30s), listing of sources_failed, and return structure. 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 comprehensive but somewhat long (5 sentences). However, every sentence provides necessary information. Could be slightly tighter but remains clear 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 the complexity (composite tool, multiple sources, partial failures, no output schema), description covers all essential aspects: what data is returned, ecosystem scope, failure handling, and version defaults. Complete for effective agent use.

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

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

Schema coverage is 100% for 2 parameters. Description adds minor context (scoped packages accepted, version defaults to latest) but no additional semantic depth 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 composite check for npm packages, listing specific data sources (deps.dev, bundlephobia) and the question it answers. It distinguishes from siblings by specifying NPM-only 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?

Explicitly says when to use: agent asks about safety/popularity/size or cost of adding a package. Also specifies what it does NOT cover (PyPI, Maven, etc.) and directs to deps.dev:version for others. Includes fallback behavior explanation.

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 return value details and usage context beyond annotations, but no behavioral traits are disclosed that are not already covered.

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

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

Two sentences, front-loaded with the main action. No redundant information. Efficiently covers purpose, optional parameters, return fields, and cross-tool 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?

No output schema, but the description explicitly lists return fields (name, summary, record_count, owner/org, url) and explains how to use the url with sibling tools. Adequate for a search tool with good annotations.

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

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

Schema coverage is 100%, but the description adds value with example values for query and org_id (e.g., 'parcels', 'RmCCgQtiZLDCtblq'). This enriches understanding beyond the schema alone.

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 action ('Search') and resource ('ArcGIS Hub catalog of open government geospatial datasets'). Specifies optional scoping by org_id and return fields. Distinguishes from siblings like query_layer and layer_info by noting the output '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?

Provides context for when to scope by organization using org_id and explains how the output feeds into sibling tools. Lacks explicit when-not-to-use guidance, but the connection to query_layer/layer_info implies a 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?

Discloses technical behavior beyond annotations: uses BGE-base-en embeddings, cosine similarity over 500-char windows, 200K char cap with truncation flag. Annotations already indicate read-only, idempotent, and non-destructive; description adds implementation details that help agent understand reliability and limits.

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

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

Four sentences, no redundancy. Purpose stated first, followed by usage guidance, then technical specifics. Every sentence adds distinct value. No filler.

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

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

Covers input constraints (200K chars), output format (passages with offsets and scores), chunking approach, and integration with sibling tools. No gaps given the absence of output schema – the description effectively replaces it.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining output behavior (returns top-N passages with character offsets and similarity scores) which is not in the schema, and clarifies the expected natural-language style for query parameter. Provides context for limit default and range.

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 semantic search inside a fetched record, with explicit use case of large documents. It distinguishes from siblings like ask_pipeworx_grounded by describing the pairing workflow, making the tool's specific role clear.

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

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

Provides explicit guidance: use when record is too large for prompt, pairs with ask_pipeworx_grounded for grounded answers. Implicitly suggests not to use when document fits in prompt. Gives actionable context on saving tokens and verifying quotes.

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 idempotentHint=true and destructiveHint=false. The description adds behavioral details: requires OAuth, returns id, always-on feed, and delivery channel specifics (email, sms with verification and cap, webhook with signing and auto-disable after failures). No contradictions with annotations.

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

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

The description is moderately long but well-structured with bullet-like points and examples. It front-loads purpose and prerequisites. Every sentence adds value, though some details (e.g., webhook HMAC) are dense. Could be slightly more concise but still effective.

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 (multiple types, delivery channels, prerequisites), the description is highly complete. It covers return value, authentication constraints, type-specific parameters, delivery options with edge cases (auto-disable, phone verification, 10/day cap). No output schema, but return (id) is mentioned.

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

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

Schema coverage is 100%, but the description adds substantial meaning: each type is explained with examples, the params object is detailed per type, and delivery options include validation rules (E.164, HTTPS only). This goes far 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 it 'Create a proactive monitoring subscription to a live-data event stream' and specifies the return (id). It distinguishes itself from siblings like 'list_subscriptions' and 'unsubscribe' by focusing on creation. Examples of supported types (e.g., sec_8k, polymarket_edge) provide concrete context.

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 when to use: for proactive monitoring subscriptions, with prerequisites (Pipeworx OAuth account) and constraints (anonymous/BYO cannot persist). It does not explicitly state when not to use, but the sibling list implies alternatives. Examples guide type selection. Slight improvement could be explicit exclusion.

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 useful context: it returns category-bucketed example questions drawn from a live catalog, and it serves as an onboarding tool. It doesn't contradict annotations and provides additional behavioral insight beyond them.

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

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

The description is effective but verbose with two paragraphs and a long list of example queries. It is front-loaded but could be more concise. The comma-separated list of queries is somewhat messy. Adequate structure but room for improvement.

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

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

Despite no output schema, the description explains the return format: category-bucketed example questions with tool and argument shape, and mentions categories and the live catalog. It also hints at meta-tools. For a discovery tool, this provides sufficient context for an agent to understand what to 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 a clear parameter description. The description reinforces this by stating 'pass topic (e.g. "finance") to focus' and explaining the behavior when omitted, adding slight extra clarity beyond the schema. Baseline is 3, but description earns a 4 for enhancing 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 provides a specific verb and resource: 'suggest questions' about Pipeworx's capabilities. It clearly states that it returns category-bucketed example questions with tool and argument shape, distinguishing it from sibling tools like ask_pipeworx. It also identifies itself as an onboarding entry point, making its purpose unambiguous.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also explains when to omit or provide the topic argument and mentions that it teaches how to call meta-tools like ask_pipeworx and entity_profile, providing clear guidance on usage 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?

Adds significant behavioral details beyond annotations: ownership enforcement, deactivation vs deletion, and relation to recent_alerts. Annotations indicate idempotent and non-destructive; description clarifies the exact nature.

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, 39 words, front-loaded with verb. Every sentence adds essential information 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?

Complete for a simple tool with one parameter and no output schema. Covers purpose, condition, effect, and relation to other tool. No gaps.

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

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

Schema covers parameter id with full description; description adds no extra meaning beyond referencing the id. Baseline 3 appropriate given 100% schema coverage.

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

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

Clearly states the action (Cancel) and resource (subscription by id). Distinguishes from sibling tools like subscribe and list_subscriptions as the inverse operation.

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 key condition (ownership enforcement) and effect (deactivation, not deletion, with historical events via recent_alerts). Does not explicitly mention when not to use or alternatives, 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: the tool returns a verdict (confirmed, refuted, etc.), structured form, actual value with citation, and percent delta. It also explains the underlying data source (SEC EDGAR + XBRL). There is 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 well-structured, starting with example triggers, then stating the purpose, followed by domain and return values. It is slightly long but every sentence adds value. Some repetition (the verdict list could be more concise) 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?

Given the tool has only one parameter, no output schema, and rich annotations, the description provides complete context. It explains the domain (company-financial claims), the data source, the return format (verdict, structured form, citation), and the benefit (replaces multiple calls). No gaps are apparent.

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

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

The single parameter 'claim' has 100% schema description coverage. The description adds further context with examples and clarifies the expected format (natural language, e.g., 'Apple's FY2024 revenue was $400 billion'). This goes beyond the schema, providing richer meaning, though the schema already describes it well.

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: verifying natural-language claims against authoritative sources. It provides example queries ('Is it true that…', 'fact check') and specifies the domain (company-financial claims). This distinguishes it from sibling tools like search or research tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes that it replaces 4–6 sequential calls, which helps agents understand when to prefer it over alternatives. However, it lacks explicit 'when not to use' guidance, which would improve clarity.

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