Arcgis Sanjuannm

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds that the tool returns per-model scores, confidence, signals, and raw response, as well as the BYO key arrangement for Anthropic. No contradictions, and the added detail is sufficient.

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 purpose, and contains no unnecessary words. It is well-structured and efficient.

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

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

Given the tool's moderate complexity, the description covers the return format (per-model data plus combined view) and the primary parameters. Without an output schema, this is sufficient 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 description coverage is 100%, so baseline is 3. The description adds some context (default model is free, _apiKey passed straight through) but does not significantly enhance understanding beyond the schema's own 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: probing LLMs for knowledge about an entity and scoring visibility. It specifies the verb (probe, score), resource (LLMs, entity), and distinguishes from siblings by detailing the specific models and use case (AI-marketing audits).

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 context on when to use: default model is Workers AI, optional Anthropic with API key, and mentions use cases like pre-launch brand checks and competitive monitoring. It lacks explicit when-not-to-use or alternatives among siblings, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: the tool is 'one fast call', returns 'structured answer with stable pipeworx:// citation URIs', and works on every tier. 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 front-loaded with the key advantage ('PREFER OVER WEB SEARCH') and is well-structured. While it is fairly long, every sentence contributes meaning by explaining scope, usage, and alternatives. Minor redundancy could be trimmed, but overall 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 tool's complexity (routing to thousands of sources) and the lack of an output schema, the description provides sufficient context: it explains the return type (structured answer with citations), suggests when to use other tools, and covers typical use cases. No major 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?

Input schema has 100% description coverage with six aliases for the 'question' parameter, all described as 'Your question or request in natural language'. The description does not elaborate further on parameter usage beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: it routes questions to one of 4,552 tools across 1160 sources and returns structured answers with citation URIs. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each.

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

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

Explicitly advises to prefer this tool over web search for factual questions, provides specific use cases and examples, and instructs when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad 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?

Beyond annotations (readOnlyHint, etc.), description reveals extra LLM call cost, explicit refusal reasons, and that extraction uses ONLY tool result, adding critical behavioral context.

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

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

Description is detailed but well-structured, front-loading purpose. Every sentence provides value, though length could be slightly reduced without loss.

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

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

With no output schema, description fully explains return structure ({answer, evidence, confidence, source, ...}) and failure modes (refusal reasons). Covers all necessary context 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 aliases clearly listed. Description restates schema info without adding new semantics, 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?

Clearly states it is a 'hallucination-resistant answer mode' for high-stakes reads, distinguishes from sibling 'ask_pipeworx' by noting preference for casual 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?

Explicitly advises when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', and when to avoid by preferring ask_pipeworx for casual lookups.

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 extensively discloses behavioral traits beyond annotations: it resolves the market, classifies the bet, fans out to category-specific data packs in parallel, and returns an evidence packet. It details response shapes (result.market, result.analysis, result.evidence), resolver contract (confidence, alternatives), parent event extraction, news fields with fallback handling, safety mechanisms (low-confidence short-circuit, closed market handling), wide-spread tradeability, and resolution-rule risk. This is very transparent.

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

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

The description is long but well-structured with labeled sections (e.g., RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, SAFETY). It front-loads the core purpose and usage. While some details could be more concise, each section serves a purpose in explaining complex behavior. The structure aids readability.

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

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

Given the tool's complexity (multiple input types, classifiers, fan-out to various data sources, many response fields) and the lack of an output schema, the description is remarkably complete. It covers the full response structure, edge cases (low confidence, closed markets, wide spreads), cancellation rules, and fallback mechanisms. No essential aspect is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the depth parameter ('quick = 2-3 evidence sources, thorough = full fan-out') and include_raw parameter ('keeps responses under ~20KB' vs 'full upstream payloads'). It also clarifies that market accepts slug, URL, or question text, which is already in the schema but is reinforced.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet), the verb (research/pull data), and the scope (one call). It also lists multiple input types (slug, URL, question text) and distinguishes itself from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on comprehensive research.

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

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

Explicit usage guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This clearly indicates when to use the tool. The description also implies when not to use it (e.g., for simple price lookups) and contrasts with sibling tools by specifying its scope.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description details data sources (SEC EDGAR/XBRL, FAERS, FDA, clinical trials), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. This provides comprehensive behavioral insight without contradicting 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, but it is front-loaded with the most important information (trigger phrases and usage priority). Every sentence adds value, though it could be slightly more structured (e.g., breaking into sections) without losing conciseness.

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

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

Given the tool has two required parameters, no output schema, but thorough annotations, the description covers the key aspects: entity types, data sources, sorting, and citation format. It does not describe the exact output format or include examples of the response, but it provides enough 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% for both parameters, but the description adds meaningful context: for 'type' it explains what data each enum value retrieves (revenue, net income, etc. for company; adverse events, approvals, trials for drug). For 'values' it provides concrete examples (tickers, drug names) and reinforces the item limits. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, with specific trigger phrases like 'Compare X and Y' and 'which is bigger'. It distinguishes between company and drug types, detailing the data sources and metrics for each. This is a specific verb+resource definition that differentiates from sibling tools such as entity_profile or 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 advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and quantifies the efficiency gain ('Replaces 8–15 sequential lookups'). This directly tells the agent when to use this tool and provides a clear alternative (sequential lookups) to avoid.

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 true, and destructiveHint false. The description adds critical behavioral details: account required, paid plan for 'thorough', 15-60s execution time, return format with findings packet, gaps, and citations. No contradictions.

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

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

The description is lengthy but front-loaded with critical account info and alternatives. Every sentence provides necessary context for a complex tool, though some trimming could improve readability.

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 (many sources, parallel execution), no output schema, the description comprehensively covers return format (findings packet, evidence, confidence, gaps, citations), timing, and edge cases (empty gaps for unsupported topics). Fully informs the agent.

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 parameter descriptions. The description adds value by explaining 'depth' in terms of number of facets and paid plan requirements, and 'question' as broad/multi-part being fine. Slight redundancy but overall helpful.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's structured data sources, contrasting with open-web search and sibling tools. It specifies the verb 'research' and the resource 'structured data sources,' making the purpose 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 tells when to use (broad/multi-part questions over structured data) and when not to (single lookup use ask_pipeworx; breaking news use ask_pipeworx). Also provides account requirements and alternative if not signed in.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that results are 'ready to call directly, no second schema lookup needed,' which is useful behavioral context beyond the annotations. No contradiction.

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

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

The description is a single paragraph that front-loads purpose and usage, followed by domain examples and return value details. It is thorough but could be slightly more concise; however, 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?

Without an output schema, the description fully explains return values: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It also notes default limit (20) and max (50), covering all necessary context.

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

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

Schema coverage is 100%, with all 6 parameters documented. The description reinforces that 'query' is a natural language description and mentions aliases, but adds no new semantic depth 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: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and explains that it returns top-N relevant tools with full schemas. This distinguishes it from sibling tools like search_datasets or scan_competitor_ai_presence, which have narrower scopes.

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

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

The description provides explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It lacks explicit when-not-to-use guidance but is otherwise 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 indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds significant behavioral context: parallel fan-out across sources, specific data returned, sunset warnings (USPTO), fallback mechanisms (GDELT→GNews), and response fields. 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: starts with example queries, then the core purpose, then details on sources and returned data. Every sentence adds value, 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 complex tool with no output schema, the description comprehensively covers all return fields: CIK, company_name, filings with URIs, fundamentals, patents, news, LEI. Also documents limitations and fallbacks, making it complete for agent understanding.

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

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

Schema coverage is 100% with both parameters described. The description enriches meaning: type is limited to 'company', value accepts ticker or zero-padded CIK, and explicitly states that names are not supported, directing to resolve_entity.

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 provides a 'full cross-source profile of a US public company in ONE parallel call' and lists the data sources and returned fields. It distinguishes itself from sibling tools like resolve_entity, which handles 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?

Explicit guidance: 'ALWAYS PREFER over chaining single-pack... when user asks for a holistic view.' Also notes that for names only, 'use resolve_entity first' — providing clear when-to-use and when-not-to-use instructions.

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

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

Description matches annotations (destructiveHint=true). Adds context about why deletion is useful (stale/done/sensitive), beyond what annotations provide. 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, first sentence action, second sentence usage. No wasted words, front-loaded.

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

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

Given single parameter, no output schema, and clear annotations, description covers all necessary context: what, when, how paired.

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

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

Schema covers 100% of parameter description. Description does not add extra semantic guidance beyond the schema's 'Memory key to delete'.

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 'Delete a previously stored memory by key' – specific verb and resource. Distinguishes from siblings 'remember' and 'recall' by naming them and contrasting action.

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: context stale, task done, clear sensitive data. Also suggests pairing with siblings, providing clear contextual guidance.

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

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

The description adds value beyond annotations by explaining the process: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. It aligns with readOnlyHint and idempotentHint, 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 concise with three distinct sentences: purpose, process, use cases. Each sentence earns its place without redundancy. Front-loaded with the main action and target audience.

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

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

With no output schema, the description adequately describes the output format (standard llms.txt markdown, single text blob). It covers the essential behavioral aspects. Minor gap: no mention of error handling for invalid URLs, but acceptable for a simple tool.

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

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

Schema description coverage is 100%, so description does not need to add much. The description restates URL purpose and mentions max_links default and max, but adds no new semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the exact resource and output. It differentiates from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on creating the standard llms.txt format.

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 lists three use cases (indexing client site, drafting own llms.txt, auditing competitor). It provides clear context but lacks explicit when-not-to-use guidance or alternatives, though the sibling tool list implies alternatives exist.

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, idempotentHint, destructiveHint. The description adds specifics about the returned schema (fields, geometry type, count, capabilities), which is useful 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?

Single sentence that front-loads the verb and resource, includes all key return types. No wasted words, 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 the tool's simplicity (one parameter, no output schema) and rich annotations, the description adequately explains what the tool returns. Missing mention of error scenarios or permissions, but for a read-only schema retrieval, this is sufficient.

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

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

Schema coverage is 100% with a clear description of the 'url' parameter. The description adds a concrete example URL format, but this is already implied by the schema description. Baseline 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 retrieves schema (fields, geometry type, record count, capabilities) for an ArcGIS layer by URL. However, it does not differentiate from siblings like 'query_layer', which might query 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?

No guidance on when to use this tool vs alternatives. With siblings like query_layer and discover_tools, explicit context would help the agent select correctly.

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

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

Annotations already declare safe read-only and idempotent behavior. The description adds value by listing exact return fields (id, type, params, timestamps, fire_count), giving agents concrete knowledge of output structure beyond annotations.

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

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

Two efficient sentences: first states action and return shape, second gives usage guidance. No wasted words, front-loaded with the most important information.

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

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

For a simple list tool with one optional parameter and rich annotations, the description fully covers purpose, return shape, and usage context. No missing gaps given the tool's complexity.

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

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

Schema description covers the sole parameter with 100% coverage. The description does not add parameter-level details beyond stating 'active subscriptions' default, but this is sufficient given high schema coverage. No additional semantic enrichment needed.

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 specifies the verb 'list' and resource 'active subscriptions', with return fields listed. Distinguishes from sibling tools 'subscribe' and 'unsubscribe' by stating purpose of reviewing before adding or finding id to cancel.

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 guides use: 'review what you're monitoring before adding more' (related to subscribe) and 'find an id to cancel' (related to unsubscribe). Provides clear context for 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?

Discloses that the tool is rate-limited to 5 per identifier per day, does not count against tool-call quota, and that the team reads digests daily. This goes beyond the annotation hints (readOnlyHint=false, destructiveHint=false) by providing real behavioral constraints and impact.

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?

Every sentence adds value: purpose, usage scenarios, formatting tip, behavioral notes. Front-loaded with clear action verb 'Tell.' No fluff or repetition.

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

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

Given the simplicity of a feedback tool (3 parameters, no output schema), the description covers purpose, usage, constraints, and parameter behavior completely. No gaps identified.

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

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

Schema coverage is 100% and all parameters are well-described. The description adds value by advising users to describe issues in terms of Pipeworx tools/packs and not paste end-user prompts, which is a semantic guideline not present in the schema.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly lists use cases (bug, feature/data_gap, praise) and distinguishes this feedback tool from sibling query tools like ask_pipeworx.

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

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

Explicitly provides when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also gives formatting guidance ('Describe the issue in terms of Pipeworx tools/packs') and mentions rate limits and quota impact.

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, and destructiveHint=false. The description adds valuable behavioral context: self-aggregating, no PII, caching strategy (5min-1h depending on window), and source (CF analytics-engine). No contradictions with annotations.

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

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

The description is two paragraphs with clear front-loading of the main action in the first sentence. The bullet points aid readability. While slightly verbose, each sentence adds value and there is no redundancy.

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

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

Given that there is no output schema, the description adequately explains the return shape (top tools, top packs, total call volume). Annotations and schema are rich, so the description's additional detail on caching and use cases makes it complete for agent understanding.

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

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

The schema already covers the single parameter 'window' with enum values and description. The description adds semantic context by explaining how shorter vs longer windows affect results ('what's hot right now' vs 'steady-state demand'), which goes beyond the schema.

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

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

The description starts with a clear verb-resource pair: 'Returns the top tools, top packs, and total call volume'. It explicitly distinguishes itself from siblings by focusing on trending data on Pipeworx, which is unique among the sibling tools (e.g., ask_pipeworx, search_datasets).

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

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

The description lists three specific use cases in bullet points, helping the agent understand when to invoke this tool (e.g., discovering hot data sources, confirming canonical choice). It does not explicitly state when not to use it, but the use cases are clear enough for selection.

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

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

Annotations indicate a safe, read-only, idempotent tool. The description adds significant behavioral context: explains the checks, fill risk validation, semantic anchor, partition filter, and response structure. 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: starts with overall purpose, then details modes, then technical nuances. While some redundancy exists (e.g., multiple mentions of partition check), it remains focused and front-loaded.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly covers the response format, fill check, semantic anchor, and partition filter. It provides sufficient context for the agent to understand and invoke the tool correctly.

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

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

Even with 100% schema coverage, the description adds meaning beyond the schema: provides example values, explains the difference between event and topic modes, and clarifies recommended usage. This helps the agent select and fill parameters correctly.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes from sibling tools (e.g., polymarket_edges, polymarket_fill_risk) by specifying its unique functionality.

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?

Clear guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scan. It recommends event mode for specific markets and explains cross-event scanning benefits. However, it does not explicitly state when not to use the 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context: explains the three model families (crypto_price, news_momentum, partition_overround, concentrated_longshot) with technical details (e.g., lognormal barrier, GDELT ratio, Kelly sizing, slippage), response structure (by_segment, fed_candidates, _diagnostics), caching behavior (KV level, 1h, keyed on knobs), and edge calculation (edge_pp_net, kelly_fraction, 24h-move warning). This far exceeds what annotations provide, with no contradictions.

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

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

The description is lengthy but front-loaded with a clear purpose sentence. It uses section-like structure (model families listed with numbers) and bullet-like points (e.g., EVERY OPPORTUNITY carries...). While dense, the detail is justified by the tool's complexity (three segments, many knobs). A slightly more concise presentation could improve readability, but it avoids irrelevant 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?

Given no output schema, the description thoroughly explains the response: top-level keys (by_segment, fed_candidates/fed_note, _diagnostics) and their contents. It covers all nine parameters (though schema already does), usage patterns (e.g., knobs for tradeable-edge filtering), caching, and diagnostics for empty segments. The tool handles multiple complex cases (Fed bets, partition overround, concentrated longshots) and the description addresses each, making it self-contained for an agent.

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 descriptive field descriptions. The description adds extra context beyond the schema: e.g., for min_liquidity, it explains 'Drop thin-book opportunities where executing the edge would walk the book past breakeven.' For max_spread_pp, it says 'anything wider eats most plausible edges.' These clarifications enhance understanding, but since the schema already covers the basics, the description's added value is notable but not overwhelming. Score reflects good supplementation.

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 specifies the verb (scan, return), resource (Polymarket markets), and distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx data disagreement. The detailed breakdown of model families further clarifies what the tool does without ambiguity.

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 includes usage guidance: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It implicitly advises when to use this tool (discovering edges) but does not explicitly mention when not to use it or compare to siblings like polymarket_arbitrage. The parameter knobs (e.g., min_liquidity, max_spread_pp) provide situational guidance for filtering, but explicit exclusions are missing.

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, openWorldHint, idempotentHint. Description adds significant context: history depth bounded by 60-day TTL, gaps in snapshots mean no scan, decay from daily closes not intraday. No contradiction with annotations.

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

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

Description is dense but well-structured, front-loaded with the key question. Every sentence adds value, though slightly lengthy. Could be trimmed slightly 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?

Despite no output schema, description details response fields (tracked, expired, snapshot_dates) and explains their contents. Covers limits (60-day TTL, gaps). Complete for a tool with 2 optional params.

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 both parameters. Description repeats defaults (14 days, 1wk window) and mentions max 30 days which is also in schema. Adds no new meaning 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 it provides edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. It differentiates fresh vs old edges, distinguishing it from sibling tool polymarket_edges which likely gives raw current edges.

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

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

Description explains the tool's purpose for temporal analysis and implies when to use it (for edge decay) vs siblings (raw edges). It doesn't explicitly state when not to use it but provides clear context with the example of fresh vs old edges.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds context: it checks live order book depth, walks the ladder, and warns about thin books and 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?

Well-structured with mode definitions and usage guidance, but overly verbose. The final paragraph repeats warnings and could be condensed. Some complex sentences could be simplified without losing meaning.

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

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

Given the complexity of two modes, numerous output fields, and no output schema, the description is thorough. It explains return values (top_of_book, vwap, slippage, verdict, etc.), edge cases (thin_legs, forced_directional_risk), and provides rationale for usage thresholds.

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 beyond the schema: clarifies the dual-mode interpretation of size_usd and side, explains defaults, and maps parameters to output fields. Completely compensates for lack of output 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 performs a realizable-vs-theoretical edge check against live CLOB order-book depth, distinguishing between single-market and basket modes with specific returned fields. It uniquely positions this tool among siblings as the pre-trade risk check for 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 requires one of market or event, details how to use each mode, and provides concrete guidance: use before acting on any polymarket_arbitrage signal or polymarket_edges trade above ~$500. It explains why partial basket fills convert an arb into an unhedged directional position.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description goes far beyond by detailing safety fields like compatibility_warning, temporal_alignment, and skipped counters. It explains the conditions under which spreads are meaningful (e.g., bet shape equivalence, temporal alignment) and warns about rare tradeable spreads. 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 lengthy (over 400 words) but well-structured with clear sections: general purpose, two modes, response details, and safety fields. It front-loads key information. The verbosity is justified by the complexity of the tool.

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

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

Given the absence of an output schema, the description thoroughly explains the response fields including leg-by-leg prices, matched spreads, compatibility_warning, temporal_alignment, and skip counters. It covers all necessary information for an agent to interpret results correctly.

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

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

Schema coverage is 100%, but the description adds significant value by explaining the two modes: topic shortcuts for pre-mapped macros and explicit tickers for custom pairings. It clarifies the semantics of the topic parameter and how overrides work.

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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses specific verbs ('cross-venue spread') and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparisons.

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

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

The description outlines two modes (topic shortcuts vs. explicit tickers) and provides guidance on when to use each. It warns that most pre-mapped topics return a compatibility_warning, indicating when spreads may not be tradeable. While it does not explicitly state when not to use the tool, the context is sufficient.

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, destructiveHint. Description adds value by specifying return of attribute rows and geometry, and mentions default parameter values (limit=50, where='1=1'). No contradiction with annotations.

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

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

Three sentences, front-loaded with purpose, lists parameters succinctly, and ends with a helpful usage tip. No unnecessary 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?

With no output schema, the description explains inputs and return of rows/geometry. Covers default values and pagination. Minor gap: does not describe error behavior or geometry format, but sufficient 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 description coverage is 100%, so baseline is 3. Description briefly mentions key parameters with examples (e.g., comma-separated out_fields, SQL-like where) but doesn't add significant detail beyond the schema's 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 queries ArcGIS Feature/Map Service layers via URL from search_datasets, with SQL-like parameters. It distinguishes itself from sibling tools like layer_info (metadata) and search_datasets (discovery).

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

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

Provides explicit guidance on sourcing URL from search_datasets and gives a practical sampling example (where='1=1', out_fields='*'). Implicitly advises when to use (querying known layers), but lacks explicit when-not-to-use or 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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining scoping: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' This goes beyond annotations and clarifies behavior. 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?

The description is three sentences long, front-loaded with the primary action, and contains no unnecessary 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?

Given the tool's simplicity, no output schema, and annotations already covering safety, the description fully explains what the tool does, when to use it, and what it returns (a value or list of keys). It is complete for an agent to invoke correctly.

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

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

The input schema has one optional parameter 'key' with a description. Schema coverage is 100%. The description in the tool text repeats that omitting the key lists all keys, but adds no new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses specific verbs (retrieve/list) and resources (values/keys), and distinguishes from sibling tools like remember and forget by explicitly mentioning them.

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

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

The description provides context on when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions pairing with remember and forget, and notes scoping. However, it does not explicitly state when not to use it or compare to siblings like search_within, but given the clear purpose, it is 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, openWorldHint, and destructiveHint as false. The description adds valuable behavioral details: how mark_read advances the read cursor, that events carry citation_uri (pipeworx:// when available), and that returns raw event payload. 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: the first states purpose and key returned fields; the second covers filtering and mark_read behavior with a note on polling and alternative endpoint. Every sentence adds value, 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?

No output schema, but the description covers what is returned (source, citation_uri, raw payload). It explains all parameters, their defaults (limit default 50, mark_read default false), and use cases. For a read-only tool with strong annotations, this is sufficiently complete. A minor gap: no mention of maximum limit or error handling.

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

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

Schema coverage is 100%, but the description adds meaning beyond schema: it explains that mark_read:true makes returned events be considered read so subsequent calls show only newer events. It also clarifies that 'since' is an ISO timestamp and 'type' filters by subscription type. 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 opens with a clear verb+resource: 'Pull fired events from your subscription feed.' It immediately distinguishes itself from siblings like 'list_subscriptions' by focusing on alerts, not subscriptions. The specificity of returned fields (source, citation_uri, raw payload) reinforces its unique 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?

The description advises that polling works fine and notes an alternative access method (GET endpoint for scripts/dashboards). It implies this tool is for interactive or programmatic use where the feed is persisted. No explicit when-not-to-use, but the context is sufficient for an agent to decide.

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

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

The description discloses sourcing behavior (SEC EDGAR, GDELT→GNews fallback, USPTO with sunset note), output structure (changes[] grouped by source, total_changes, citation URIs), and does not contradict annotations (readOnlyHint, 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 well-structured and front-loaded with examples. It is slightly long (4-5 sentences) but each sentence adds value. No redundant information.

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

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

Given the tool's complexity (multiple sources, fallback, three parameters with different formats), the description covers essential aspects. No output schema, but the return structure is described. Adequately 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?

With 100% schema description coverage, baseline is 3. The description adds extra meaning: explains 'since' accepts ISO date or relative shorthand with examples, 'value' can be ticker or CIK, and 'type' is restricted to 'company'. This justifies a score of 4.

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

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

The description clearly states the tool retrieves recent changes for a company (SEC filings, news, patents) within a time window. It distinguishes itself from the sibling 'entity_profile' tool by specifying that 'entity_profile' should be used for static profiles.

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

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

The description provides explicit usage scenarios ('What's new with X', 'latest on Y') and fallback logic (GDELT→GNews). It also tells when to use an alternative ('Use entity_profile instead when you want the static profile').

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

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

Annotations indicate idempotent, non-destructive write. Description adds scope ('scoped by your identifier') and retention details (persistent for authenticated, 24h for anonymous), which are valuable beyond annotations.

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

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

Three sentences cover purpose, usage, and additional context. No wasted words, front-loaded with the core action. Could slightly improve structure but very efficient.

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

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

For a simple tool with 2 parameters and no output schema, the description fully covers scope, persistence, and complementary tools. Annotations handle safety profile. Complete and sufficient.

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

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

Schema description coverage is 100% with clear descriptions for key and value. The tool description does not add new parameter information beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse across conversations/sessions, using specific verb 'save' and resource 'data as key-value pairs'. It distinguishes itself from siblings by mentioning 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 states when to use ('when you discover something worth carrying forward') and provides alternatives ('Pair with recall to retrieve later, forget to delete'). Clear guidance.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses that each call cascades through multiple internal endpoints, replacing 2-3 manual lookups. It also details the exact output format for each entity type, including citation URIs, which is not captured in annotations.

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

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

The description is efficiently structured: it opens with example queries, then a directive, followed by detailed types. Every sentence serves a purpose, though it could be slightly more concise by merging some details.

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

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

Despite lacking an output schema, the description compensates by fully describing the return values (ticker, CIK, company_name, citation for company; RxCUI, ingredient, brand for drug). It also mentions internal cascading, making the tool's behavior fully transparent.

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 defines parameters well. The description adds value by providing concrete examples ('AAPL', '0000320193', 'ozempic') and clarifying accepted formats for the value parameter, enriching 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 user-spoken names to canonical identifiers required by other tools. It gives specific examples like ticker, CIK, RxCUI and explicitly distinguishes it as the first tool to use when needing an ID, differentiating it from siblings.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.', providing a clear directive for when to invoke this tool. It also gives example queries that map to common use cases, making it easy for an agent to decide to use it.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by revealing it internally calls ai_visibility_check, ranks entities by score, and returns a ranked list with specific fields (score, confidence, signal density). This behavioral detail is beyond what annotations provide. No contradictions are present.

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 (4 sentences) and front-loaded with the primary action and purpose. Every sentence adds value: purpose, sub-tool usage, use case example, and output description. No fluff or redundancy.

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

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

Given moderate complexity (4 parameters, no output schema), the description adequately explains the overall behavior, input, and output. It mentions return fields (score, confidence, signal density) and provides a use case. However, it does not detail potential error states or prerequisites for optional parameters (e.g., needing an API key for Anthropic). The schema covers those, so completeness is good but not exhaustive.

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% (all 4 parameters have descriptions), so the baseline is 3. The description reinforces the parameter meanings (e.g., 'First entry treated as the subject') but does not add new semantics beyond what is already in the schema. Therefore, the description meets the minimum but does not enhance parameter understanding.

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

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

The description clearly states the verb 'Compare AI visibility across multiple entities side-by-side' and identifies the resource (AI visibility). It distinguishes from sibling tools like ai_visibility_check (single entity check) and compare_entities (general comparison) by specifying the exact functionality and output (ranked list with scores, confidence, signal density). The purpose is specific and unambiguous.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and gives an example question ('does Claude know about us as well as our competitors?'). However, it does not explicitly state when not to use this tool nor compare it to alternatives like ai_visibility_check for single-entity checks. Implicitly, it suggests use over single checks for multi-entity comparisons, but lacks explicit exclusions.

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

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

Annotations already declare safe operations. Description adds critical behavioral details: partial failures degrade gracefully, bundlephobia's first measurement takes 5-30s, sources_failed list on timeout. No contradictions.

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

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

Description is detailed and front-loaded with primary purpose. While it contains several clauses, every sentence adds value. Could be slightly more structured but remains efficient.

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

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

Given the tool complexity (composite call) and no output schema, description adequately explains return structure: summary block, per-advisory details, links, alternative versions. Missing details like pagination or format, but sufficient for basic understanding.

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 description adds extra context: scoped packages accepted for 'package', default version behavior for 'version'. Provides meaningful usage guidance beyond schema.

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

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

The description clearly states it is a composite check for adding an npm package, covering license, advisories, version history, and bundle size. It distinguishes from sibling tools like bet_research or deep_research by specifying the exact use case.

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

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

Explicitly states when to use: when an agent asks about safety, popularity, size, or cost of adding a package. Also notes limitations (NPM only in v1) and directs to deps.dev:version for other ecosystems.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the returned fields (name, summary, record_count, owner/org, url), 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?

Two concise sentences with no wasted words. Front-loaded with action and examples, followed by return structure. Every sentence adds value.

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

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

Given the 3 fully documented parameters, strong annotations, and no output schema, the description provides sufficient context: what the tool does, what it returns, and how to use the result with sibling tools.

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

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

Schema coverage is 100%, so parameters are fully documented. The description adds minimal semantic value, only illustrating the query parameter with example keywords. 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?

Clearly specifies the verb 'Search' and the resource 'San Juan County GIS open geospatial datasets.' Provides concrete examples like parcels, addresses, zoning. Distinguishes from sibling tools like query_layer and layer_info by focusing on search for dataset metadata.

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

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

States the action (keyword search) and indicates the output should be used with query_layer/layer_info. Provides clear context on when to use but does not explicitly exclude 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 substantial behavioral details beyond annotations: it specifies the embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K) with truncation and flagging. Annotations already indicate read-only, idempotent, open-world, non-destructive behavior, and the description complements them 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?

The description is concise and well-structured: it starts with the core action, then explains when to use, then provides technical details. Every sentence adds value with no redundancy.

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

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

Given the tool's complexity (semantic search, chunking, truncation), the description covers all necessary aspects: how to use, what is returned (passages with offsets and scores), when to use, pairing with another tool, and technical limitations (cap, truncation). No output schema exists, but return values are clearly described.

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 contextual examples (e.g., 'SEC 10-K body' for text, 'supply-chain risk' for query) but does not introduce new semantic constraints or details beyond the schema descriptions. The examples are helpful but not sufficient to raise the score.

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 semantic search inside a fetched record, with specific verb ('search inside') and resource ('a fetched record'). It distinguishes itself from siblings by explicitly pairing with ask_pipeworx_grounded and describing its niche (searching within large records).

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

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

The description explicitly states when to use this tool: when the record is too big to fit in the prompt. It also provides a pairing guidance with ask_pipeworx_grounded, suggesting a workflow. No exclusion of alternatives is needed as the use case is clearly scoped.

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=false, idempotentHint=true, destructiveHint=false. The description adds significant behavioral details: returns subscription id, requires OAuth, explains delivery channel constraints (phone verification, cap, webhook auto-disable). No contradictions. Could mention failure behavior or cost methods.

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

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

The description is front-loaded with the core purpose, but the second sentence is long (7+ lines) and dense with examples. While every part adds value, breaking it into bullet points or shorter sentences could improve readability 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 no output schema, the description mentions returns 'new subscription id' but does not detail the full response structure. It covers prerequisites, constraints, and examples well. However, not all enum types (patent_grant, clinical_trial) receive as much explanatory depth as the first three, and the tool's effect on the event feed is implicit.

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 rich context for all parameters: enumerates type-specific filters for all five subscription types (including patent_grant and clinical_trial), explains delivery options (email, sms, webhook with constraints and HMAC signing). This goes well beyond the schema definitions.

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

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

The description clearly states the verb 'Create' and the resource 'proactive monitoring subscription to a live-data event stream'. It distinguishes itself from siblings like 'list_subscriptions' and 'unsubscribe' by focusing on creation of new subscriptions.

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

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

The description provides explicit context: requires Pipeworx OAuth account, lists supported types with examples, and notes prerequisites (phone verification for sms, caps like 10/day). However, it does not explicitly mention when not to use this tool (e.g., if only listing or removing subscriptions) or directly reference sibling tools as 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 provide readOnlyHint, openWorldHint, etc. The description adds value by explaining it is the onboarding entry point, returns examples with tool calls, and can filter by topic. 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 comprehensive but not overly verbose. It is front-loaded with common user queries and each sentence contributes useful information. Minor room for tightening, but overall 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 rich annotations, full parameter coverage, and no output schema, the description adequately explains the tool's return value (category-bucketed examples) and usage. Complete for its purpose as an onboarding 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% for the single parameter. The description adds meaning by listing example topics and advising to omit for a full spread, going 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 clearly states the tool's purpose: it returns category-bucketed example questions with exact tool+argument shapes, serving as an onboarding entry point. It distinguishes itself from siblings like ask_pipeworx and discover_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 instructs to use this tool first when unfamiliar with Pipeworx's capabilities or to learn meta-tools. Mentions optional topic filtering but does not explicitly state when not to use it, 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?

Beyond annotations (idempotentHint=true, destructiveHint=false), description adds key behavioral detail: soft-deletion, keeping historical events available via recent_alerts. No contradiction with annotations.

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

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

Two concise sentences, no redundancy, directly conveys essential information. 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?

For a simple 1-param tool with no output schema, description covers purpose, behavioral traits, and usage constraints. Adequate for agent to understand when and how to invoke.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add extra parameter-level detail beyond schema's 'Subscription id (uuid) returned by subscribe'. Ownership enforcement is tool-level, not parameter-specific.

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 states 'Cancel a subscription by id' which is a specific verb+resource. Clearly distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

States ownership enforcement: 'you can only cancel your own subscriptions', providing clear context for when to use. Implicitly excludes canceling others' subscriptions, but no explicit alternative mentioned.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. Description adds return format (verdict types, structured form, actual value with citation, percent delta) and notes it replaces 4-6 sequential calls, providing 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?

Description is concise, front-loaded with trigger phrases, and every sentence adds value. No redundant or extraneous 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 single parameter, good annotations, and no output schema, the description fully covers purpose, usage, domain, return values, and advantages over alternatives. Contextually complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% with one parameter 'claim' clearly described. Description adds examples of claim formats and domain restrictions, adding meaning beyond the schema. No enums or nested objects.

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 tool verifies natural-language factual claims, specifically company-financial ones (revenue, net income, cash position) using SEC EDGAR + XBRL. It includes trigger phrases and distinguishes from siblings by replacing multiple sequential calls.

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: 'whenever the agent needs to check whether something a user said is factually correct' and specifies the domain (US public company financial claims). However, it does not mention when not to use or recommend alternatives among siblings.

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