Arcgis Seattle

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

The description adds context beyond annotations: explains cost model (free Workers AI, BYO key for Anthropic), return structure (per-model score, confidence, signals, raw_response, combined view), and that the tool is read-only and idempotent (consistent 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, no fluff. Front-loaded with main function and output, then cost/activation, then return structure. Every sentence earns its place.

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

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

Description covers output structure, use cases, and parameter activation. No output schema needed as returns are described. Sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that `_apiKey` is only needed for Anthropic, `models` lists probe targets, and `context` disambiguates entities, surpassing mere schema replication.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It differentiates from sibling tools by focusing on multi-model visibility assessment with specific output details.

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

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

The description specifies use cases like AI-marketing audits and brand checks, and explains default vs. paid model access. However, it does not explicitly exclude alternative tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds that it routes to 4,552 tools across 1160 sources, fills arguments, and returns structured answers with pipeworx:// citation URIs. No contradiction, but could mention rate limits or token usage.

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

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

The description is well-structured with bold emphasis and examples. It front-loads the key message of preferring over web search. However, it is somewhat verbose; several lines could be tightened 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 (many sources, 33 siblings), the description is comprehensive. It explains use cases, when to step up to alternatives, and provides concrete examples. No output schema exists, but the return format (structured with citations) is adequately described. Satisfies all informational needs for selecting and invoking the tool.

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

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

All 6 parameters are aliases for 'question' with 100% schema description coverage. The description explains the question parameter accepts natural language and lists acceptable aliases. Adds value by showing examples of valid questions. However, it does not clarify any input constraints beyond natural language.

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 answers factual questions from a vast array of authoritative sources with structured answers and citations. It distinguishes itself by naming specific data domains (SEC filings, FDA, etc.) and contrasts with siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and instructs for most factual questions. Provides clear criteria for when to use this tool vs siblings: use ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for multi-part broad questions. Lists concrete example questions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true. The description adds context on refusal reasons (e.g., 'not_in_source', 'no_tool_match') and the exact return fields, which is valuable beyond annotations.

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

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

The description is front-loaded with the key purpose and is well-structured. Every sentence adds value, providing necessary details without redundancy.

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

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

Given the complexity (6 params, no output schema), the description fully explains return format and refusal reasons, compensating for the missing output schema and ensuring the agent knows 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% with detailed aliases. The description does not add meaning beyond the schema for parameters, focusing instead on overall behavior. 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 is a 'hallucination-resistant answer mode for high-stakes reads.' It specifies that it extracts answers using only the tool result, distinguishing itself from sibling ask_pipeworx 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?

Explicit guidance on when to use ('high-stakes reads, when answer will be quoted, cited, or acted on') and when not ('prefer ask_pipeworx for casual lookups'), including a cost trade-off of one extra LLM call.

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 readOnly, idempotent, and non-destructive. The description goes far beyond by detailing safety behaviors: low-confidence matches short-circuit, closed markets skip fan-out, spread warnings, resolution-rule risk, and fallback mechanisms. No contradiction with annotations.

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

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

The description is lengthy but well-structured and front-loaded with the core purpose. Every sentence adds useful detail (classifiers, fan-out examples, response shapes, resolver contract). While concise by necessity, it could be slightly shortened without losing value, but the structure is logical.

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

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

Given no output schema, the description completely explains return values: result.market, result.analysis, result.evidence, resolver contract with market_match_confidence, parent_event extractor, news fields, and safety behaviors. It covers edge cases (low confidence, closed markets, wide spreads, resolution-rule risk) thoroughly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds extra meaning beyond the schema: explains the depth parameter with quick vs thorough behavior, details the market parameter's multiple input formats, and recommends when to use include_raw. This adds significant value beyond baseline 3.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data, and specifies the input formats (slug, URL, question) and outputs (evidence packet + comparison). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on a single bet research task.

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

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

Explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides examples of when fan-out occurs or short-circuits (low confidence, closed markets). It clearly guides the agent on when to use this tool.

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

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

Discloses that it pulls latest 10-K data, handles off-calendar fiscal years, sorts results by primary metric, returns paired data with citation URIs. Complements readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations without contradiction.

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

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

Front-loaded with query examples, then states operation, then entity-specific details. 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?

Given 2 parameters, 100% schema coverage, no output schema, description covers input constraints (2-5), data sources, sorting, and output format (paired data + citation URIs). Complete enough for agent to use correctly.

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

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

Schema has 100% coverage, but description adds meaning: explains what data is fetched per type (SEC EDGAR for companies, FAERS for drugs) and format for values (tickers/CIKs vs drug names).

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 starts with common query patterns and explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call,' clearly distinguishing from entity_profile (single entity) and sequential 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 says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example queries. Gives data source details for each type, though lacks explicit exclusions vs other comparison tools in sibling list.

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 show readOnlyHint=true, idempotentHint=true, etc. Description adds: tool is not open-web search, it decomposes questions, routes in parallel, returns findings with evidence/sources/gaps, and mentions expected latency (15-60s). All consistent with annotations and adds rich 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 dense but well-structured. Front-loaded with account requirement and alternative. Each sentence adds value, though length is justified by complexity. Could be slightly more concise, but efficient for the information provided.

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

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

No output schema, but description explains output format: findings packet with evidence, confidence, source, fetched_at, citation, and explicit gaps. Also covers edge cases (empty gaps for out-of-catalog topics). Expected latency and alternative tools are mentioned. Complete for a tool with 2 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 descriptions for both params. Description adds meaning: defines depth values (quick=3, standard=5, thorough=8) and clarifies that question can be broad/multi-part. Also adds account requirement for thorough. Slight improvement over schema.

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

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

The description clearly states it performs grounded multi-source research across 1160 structured data sources in one call, with examples like 'compare X and Y's regulatory + financial exposure'. It distinguishes from siblings by specifying when to use ask_pipeworx for single lookups or current news.

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

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

Explicit when-to-use: broad/multi-part questions over structured data. Explicit when-not-to-use: for single lookups use ask_pipeworx, for breaking news prefer ask_pipeworx. Also details account requirements and that depth:'thorough' needs a paid plan. Provides alternative tool: ask_pipeworx.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows it's safe and idempotent. The description adds valuable behavioral context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This informs the agent about the output format and readiness for subsequent calls, going beyond the annotations.

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

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

Two sentences long, front-loaded with the core purpose, and highly efficient. Every phrase earns its place: the first sentence states what it does and lists use cases; the second describes the return value and key benefit. No filler or redundancy.

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

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

Given the tool's simplicity (6 parameters, many aliases; no output schema), the description is adequately complete. It explains the return value (top-N tools with schemas and examples) and the 'ready to call directly' benefit. It does not cover pagination or error handling, but for a discovery tool with annotations already covering safety, this is sufficient. Slightly more detail on what 'top-N' means could improve, but it is still strong.

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 value by including examples like 'look up FDA drug approvals' and 'analyze housing market trends,' which illustrate the natural language usage. It also notes that the query accepts aliases (q, task, search, description), augmenting the schema definitions. Thus, the description provides extra semantic guidance beyond the bare 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 begins with 'Find tools by describing the data or task,' clearly stating the tool's purpose. It lists specific domains (SEC filings, financials, FDA drugs, etc.), making the scope concrete. The name and title 'discover_tools' / 'Discover Tools' match perfectly, and it is distinct from sibling tools which are specific tools discovered by this one.

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

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

Explicitly states 'Use when you need to browse, search, look up, or discover what tools exist for...' and advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear guidance on when to use. It does not explicitly list when not to use, but the instruction to call first implies the alternative is to call a specific tool directly if already known.

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

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

The description adds significant behavioral context beyond annotations: details the data sources fanned out across, specific return fields, and the soft-fail for USPTO PatentsView API sunset. This complements the readOnlyHint and idempotentHint 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 paragraph but packs in necessary information: examples, usage guidance, data sources, return fields, and caveats. While comprehensive, it could be slightly more structured (e.g., bullet points) for easier scanning, but remains concise overall.

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 an output schema, the description is highly complete. It enumerates all return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and mentions the parallel execution nature, ensuring the agent understands 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 value by explaining the accepted formats (ticker or zero-padded CIK) and explicitly stating that names are not supported, directing to resolve_entity. This clarity goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose with natural language examples and a concise definition: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from sibling tools and mentions preferred usage over chaining 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?

Explicitly states when to use this tool ('ALWAYS PREFER over chaining single-pack... when the user asks for a holistic view') and when not to use it ('Names not supported — use resolve_entity first if you only have a name'), providing a clear alternative.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false; description adds context about clearing sensitive data, consistent 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 sentences, front-loaded with action, 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?

Single parameter with full schema coverage, annotations present, no output schema needed; description fully covers usage and effect.

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

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

Schema coverage is 100% with parameter 'key' described as 'Memory key to delete'. Description adds minimal new meaning beyond stating 'by key'.

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 'Delete a previously stored memory by key' with clear verb and resource. It distinguishes from siblings like 'remember' and 'recall'.

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

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

Explicitly states when to use: when context is stale, task is done, or to clear sensitive data. Also suggests pairing with remember and recall.

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

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

Annotations already indicate safe, idempotent, open-world behavior. The description adds the process (fetches page, extracts data, emits markdown) and output format, providing behavioral context beyond annotations without contradiction.

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

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

The description is a single paragraph of three sentences: purpose, process, use cases. Every sentence serves a clear function with no extraneous words, making it efficient and well-structured.

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

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

Given the tool's simplicity (2 params, no output schema), the description adequately covers what it does, how it works, and output format. It is complete for agent decision-making without needing additional details.

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely repeats the schema text for both 'url' and 'max_links', adding minimal new meaning (e.g., example for url). No significant enhancement beyond schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and the resource 'llms.txt file'. It distinguishes itself from sibling tools, none of which perform the same function.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitor indexing. It does not mention when not to use or alternatives, but the provided context is clear and actionable.

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

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

Annotations already indicate safe read operations (readOnlyHint, idempotentHint). The description adds valuable detail about the exact schema components returned (fields, geometry type, record count, capabilities), which goes beyond annotations. No contradictions.

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

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

One sentence, 15 words, front-loaded with the essential action and resource. No extraneous information. Every word earns its place.

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

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

Given the tool's simplicity (1 param, no output schema) and the rich annotations, the description covers what the tool returns and its purpose completely. No gaps for an agent to invoke it correctly.

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

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

The single parameter 'url' is already well-described in the input schema (100% coverage). The description reaffirms it as a Feature/Map Service layer URL, adding no further meaning beyond the schema. 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 it retrieves an ArcGIS layer's schema (fields, geometry type, record count, capabilities) by URL. This is a specific verb-resource pair and distinguishes from sibling tools like query_layer (which queries data) and search_datasets (which searches 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 implies you use this when you need the schema of a specific ArcGIS layer, but there is no explicit guidance on when to choose this tool over alternatives like query_layer or search_datasets. No exclusions or when-not-to-use context is provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds value by listing the specific return fields (id, type, params, created_at, etc.) and notes that only active subscriptions are returned unless 'include_inactive' is true. 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 concise sentences, each adding distinct value: the first states the core function, the second provides actionable usage context. No superfluous content.

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

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

Given the simple single-parameter input and no output schema, the description adequately covers purpose, return fields, and usage context. It does not address pagination or ordering but that is not critical for this tool.

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

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

Schema coverage is 100% and the schema already describes the single optional parameter 'include_inactive'. The description does not add additional semantic meaning beyond the schema, meeting the baseline for high coverage.

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

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

The description clearly states the verb 'List' and the resource 'the caller's active subscriptions', specifying the scope. It differentiates from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description explicitly advises using this tool to 'review what you're monitoring before adding more' and 'to find an id to cancel', providing clear context for use, though it does not mention when not to use it.

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

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

Discloses rate limit (5 per identifier per day), free status, no quota impact, and that feedback is reviewed daily and influences roadmap. This adds behavioral context beyond annotations, which are neutral.

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

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

Concise and well-structured: front-loaded with purpose, followed by usage scenarios, then constraints and tips. No unnecessary sentences; each sentence contributes 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 3-param tool with no output schema, description covers all necessary aspects: when to use, how to structure input, behavioral constraints, and team response. No gaps.

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

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

Schema already provides descriptions for all parameters (100% coverage). Description reinforces usage by elaborating on enum values and advising on message content (specific, 1-2 sentences). Adds practical guidance without redundancy.

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

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

Description clearly states the tool's purpose: to send feedback about bugs, missing features, or praise. It distinguishes from siblings by focusing on feedback submission, contrasting with query/research tools like ask_pipeworx or deep_research.

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

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

Explicitly lists specific use cases (bug, feature/data_gap, praise) and instructs to describe in terms of Pipeworx tools/packs, avoiding end-user prompts. Provides clear when-to-use guidance.

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

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

Discloses data source (CF analytics-engine), absence of PII, caching behavior (5min-1h), and self-aggregating nature. Adds context beyond annotations (readOnlyHint, etc.) without contradiction.

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

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

Concise (~100 words), with bullet-like enumeration and a clear closing note on caching. No unnecessary words; each sentence serves a purpose.

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

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

Given single optional parameter and no output schema, the description fully covers purpose, use cases, data provenance, and caching. An agent can confidently decide when 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?

Only one parameter with 100% schema coverage; description adds interpretive guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.'

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

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

Describes specific verb/result: 'Returns the top tools, top packs, and total call volume...' with clear scope and three enumerated use cases, distinguishing it from sibling tools like 'ask_pipeworx' or '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 lists three concrete scenarios when to use (e.g., 'discovering what data sources are hot', 'confirming a popular tool'), and implicitly advises against using for narrower queries by mentioning alternative contexts.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds extensive context: discusses algorithm details (semantic anchor, partition filter, fill check), explains when an overround exists only at last-trade, and describes return values like opportunities[] and partition_check.

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 purpose and usage, but is quite long with technical details. While well-structured, it could be more concise without losing essential 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 fully explains the return format (opportunities array with fields, partition_check, fill check results). It covers edge cases (placeholder filter, low similarity) and references a sibling tool for custom sizing.

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 description adds meaning beyond schema: explains the event parameter accepts full URLs, describes the topic parameter's behavior (searches related events, runs comparator on union), and provides example inputs.

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: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description provides explicit guidance: call with no args for trending scan, use event for specific market, use topic for cross-event scanning. It includes examples, recommendations (event recommended for specific market), and a fill check section advising when not to trade.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds rich behavioral details: caching at KV level, response structure with diagnostics, mathematical models (lognormal, GDELT, partition overround), and filtering logic. No contradiction.

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

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

Description is long but well-structured with sections and front-loaded core purpose. However, it includes extensive mathematical detail that could be condensed for quicker comprehension.

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

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

For a complex tool with 9 parameters, no output schema, and no nested objects, the description covers all necessary aspects: response structure, model families, filtering knobs, caching, diagnostics, and edge cases (Fed bets). Very complete.

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

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

Schema has 100% coverage with descriptions. Description adds context on the overall role of parameters (e.g., tradeable-edge knobs, why min_kelly doesn't filter partition arbs) but does not significantly enhance individual parameter meaning beyond schema.

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

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

Description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and explicitly positions it as 'what should I bet on today'. It distinguishes from siblings by focusing on edge detection with specific model families.

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

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

Provides extensive context: discovers opportunities without paging, explains tradeable-edge knobs, and mentions Fed bets are excluded from ranking. However, it does not explicitly state when not to use this tool or name specific sibling alternatives.

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

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

The description adds significant behavioral context beyond annotations: it explains snapshot-based read behavior, limits (60-day TTL, gaps on cache-miss), and nuances of decay computation. No contradiction with 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 thorough and well-structured, with clear sections for purpose, response fields, and limits. It is slightly long but each sentence adds value; 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?

Given the complexity of the tool (time-series, decay, multiple response objects) and lack of output schema, the description fully explains all return fields (tracked, expired, snapshot_dates) and limitations. No gaps in 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%, so baseline is 3. The description reiterates default values and constraints already in schema, providing no additional semantic meaning beyond what the schema provides. It does not introduce new parameter insights.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry from daily polymarket_edges snapshots' and answers specific questions about edge longevity and trends. It distinguishes itself from siblings like 'polymarket_edges' (raw snapshots) by focusing on temporal analysis.

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

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

The description explains the tool's purpose and implicit use case (comparing edge persistence) but does not explicitly state when to avoid it or provide direct alternatives. However, the context is clear enough for an AI to infer when to use this over related tools.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and no destructiveness. The description adds behavioral details about order book checks, verdict types, and mode behaviors, without contradicting annotations.

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

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

The description is long but well-structured with clear separation of modes and use of capitalization. Every sentence adds value, though some density could be reduced for quicker scanning.

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

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

Despite no output schema, the description lists all return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and covers edge cases like thin legs and partial fills. It is comprehensive for the tool's complexity.

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

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

All parameters have descriptions in schema, and the description adds significant context: explains `side` defaults per mode, interprets `size_usd` differently for single vs basket (spend vs notional), and notes constraints (clamp 10–1M). This goes well beyond the schema.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', specifies single-market and basket modes, and lists return fields. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by describing its specific role.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and warns about thin books and partial fills. It doesn't explicitly state when not to use, but provides strong 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint false. The description does not contradict these and adds substantial behavioral context: compatibility_warning cases, skipped_cross_type/subtype counters, temporal alignment checks, and the fact that many topic shortcuts may not yield tradeable spreads. This goes well beyond what annotations provide.

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

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

The description is dense and well-structured with clear sections for modes, response fields, safety fields, and caveats. It is somewhat long but each sentence adds necessary detail for correct usage. Minor conciseness could be achieved, but it is appropriate given the tool's complexity.

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

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

Despite no output schema, the description thoroughly explains the response structure: leg-by-leg prices, matched spreads, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It covers edge cases like non-equivalent bet shapes and temporal mismatches, making it complete for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100%, and each parameter already has a description. The description adds value by explaining the two modes, providing concrete examples for topic values, and noting that explicit tickers override the topic-mapped side. This helps the agent understand how to use the parameters effectively.

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 calculates cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by explicitly focusing on two venues, and mentions 'pre-mapped macro shortcuts' which differentiate it from generic search tools.

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

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

The description provides explicit guidance on two modes (topic shortcuts vs explicit tickers), explains when spreads are meaningful via compatibility_warning and temporal_alignment, and warns that most pre-mapped topics currently return warnings, so they are not automatically tradeable. This gives clear when-to-use and when-not-to-use advice.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that tool returns 'attribute rows (and geometry)', consistent with read-only 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?

Two sentences, zero waste, front-loaded with purpose. Every sentence adds unique information: purpose, parameter syntax example, and sampling tip.

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

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

Tool has 6 parameters with full schema coverage but no output schema. Description explains query syntax, pagination (limit, offset), and return content (attributes and geometry). Lacks mention of ordering or field selection nuance but schema handles those adequately.

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

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

Schema coverage is 100% with descriptions for all 6 parameters. Description adds value by explaining SQL-like syntax for 'where', comma-separated 'out_fields', and providing a sample usage tip ('where="1=1" + out_fields="*" to sample').

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 uses specific verb 'Query' and resource 'ArcGIS Feature Service / Map Service layer by its url (from search_datasets)', clearly distinguishing it from sibling tools like search_datasets (which finds layers) and layer_info (which gets 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?

Description implies usage context: having a layer URL from search_datasets. Provides example of sampling data with where='1=1' and out_fields='*'. Does not explicitly exclude alternatives but context is clear.

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

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

Annotations already indicate readOnlyHint and no destruction. The description adds behavioral context about scoping to user identifier (anonymous IP, key hash, account ID), which is useful beyond annotations. No contradictions.

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

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

Three focused sentences with no wasted words. Action is front-loaded: 'Retrieve a value previously saved via remember, or list all saved keys'. 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 read tool with one optional parameter and no output schema, the description covers behavior (with/without key), scoping, and pairing with siblings. It is fully self-contained and adequate for agent use.

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

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

Schema coverage is 100% and describes the parameter well. The description essentially echoes the schema's behavior (omit key to list all), adding no new semantic depth beyond what the schema already conveys.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, using specific verbs and resource references. It distinguishes itself from siblings like 'remember' and 'forget' by naming 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 clear use cases (e.g., retrieving user's target ticker, address, research notes) and implies when not to use (forget for deletion, remember for saving). It lacks explicit 'when not to use' but is still helpful.

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 safe and idempotent behavior. The description adds valuable context: the side effect of mark_read updates read status, and the feed is persisted. 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 4-5 sentences, each serving a purpose: purpose, return details, filtering options, side effect, and alternative access. No redundancy or fluff.

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

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

Adequately covers the tool's role with 5 optional parameters, no output schema, and rich annotations. Mentions default limit (50) via schema, but could mention pagination or order of events. Still sufficient for most use cases.

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

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

Schema coverage is 100% with basic descriptions; the description adds examples (e.g., 'sec_8k' for type) and clarifies behavior of mark_read ('flag returned events read so the next call only shows newer ones'), adding value beyond the schema.

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

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

The description clearly states the action ('Pull fired events') and the resource ('your subscription feed'), with specific details on returned fields (source, citation_uri, payload). It distinguishes itself from siblings like list_subscriptions or recent_changes by focusing on event alerts.

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

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

Provides context for polling ('Polls work fine') and an alternative access method (HTTP endpoint for scripts/dashboards). Includes filtering examples (type 'sec_8k', ISO timestamp) but does not explicitly state when to avoid this tool or contrast with all siblings.

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. Description adds valuable behavioral details: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO with sunset note, and return structure including changes[] grouped by source, total_changes, and citation URIs. 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?

Well-structured with example queries first, then behavior explanation, then sibling differentiation. 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 description fully explains return format (changes[] grouped by source, total_changes, citation URIs). Also covers multiple data sources, fallback logic, and soft-fail scenarios. Complete for a complex tool.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning: explains that 'since' accepts ISO date or relative shorthand with typical monitoring recommendation, 'value' is ticker or zero-padded CIK, 'type' is only 'company'. Exceeds baseline.

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

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

Description begins with concrete example queries, clearly states the tool delivers a change feed for a company in a configurable window via a single parallel call, and explicitly distinguishes itself from the sibling tool entity_profile.

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

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

Explicit guidance on when to use this tool (change feed queries) and when to use the alternative entity_profile. Also explains fallback behavior between GDELT and GNews.

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

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

Discloses scoping by identifier, persistence differences between authenticated and anonymous users (24 hours), and implicitly confirms idempotency (setting same key updates). 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 wasted words, purpose front-loaded, structure logical.

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

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

For a simple key-value storage tool with good annotations and schema, the description covers purpose, usage, behavior, and pairing, making it fully complete.

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

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

Schema descriptions already cover the two parameters well. Description adds usage examples and pairing context, improving semantics beyond schema.

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

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

The description clearly states the tool saves data for later reuse, uses a specific verb and resource, and distinguishes from siblings recall and forget by name.

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

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

Provides explicit when-to-use (when you discover something worth carrying forward), gives examples (resolved ticker, target address), and mentions pairing with recall and forget for a complete workflow.

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

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

Annotations already indicate readOnly, openWorld, and idempotent behavior. The description adds value by explaining that each call cascades through multiple endpoints and specifies exact return values for each type (ticker, CIK, company name, citation URI for company; RxCUI, ingredient, brand, citation for drug). 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 examples and structured by entity type. It is moderately concise, with every sentence serving a purpose. Could be slightly tighter, but overall efficient and well-organized.

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, full schema coverage, rich annotations, and lack of output schema, the description compensates by detailing return values and internal behavior. It provides sufficient context for an AI agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances with concrete examples (e.g., 'ticker (AAPL), CIK (0000320193), or name' for company) and notes auto-disambiguation, adding meaning beyond the schema's basic type constraints.

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

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

The description clearly states the tool's purpose: resolving a user-spoken name to a canonical identifier other tools require. It provides specific examples (ticker, CIK, RxCUI) and distinguishes the tool as a composite lookup that replaces multiple manual steps, making it distinct from siblings like entity_profile.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID,' giving clear when-to-use guidance. It also details supported entity types and input formats. While it doesn't list when-not-to-use or alternative tools, the context and examples provide sufficient direction for an AI agent.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, indicating safe, idempotent behavior. Description adds that it probes each entity, ranks by score, and returns a ranked list with score/confidence/signal density. No contradictions; adds moderate context beyond annotations but does not discuss caching, rate limiting, or further behavioral details.

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

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

Two sentences, purpose front-loaded, every sentence earns its place. No filler, easy to scan.

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

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

Given moderate tool complexity (4 params, no output schema), description covers input (entities, models, context, apiKey), behavior (probes each entity), and output (ranked list with score, confidence, signal density). Sufficient for selection and invocation.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. Description adds valuable context: 'entities' first entry is subject, 'models' includes default and condition for apiKey, 'context' disambiguates common names. This meaningfully enriches 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?

Description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. Distinguishes from sibling ai_visibility_check (single entity) and compare_entities (different purpose).

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

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

Explicitly states usefulness for competitive AI-marketing audits with an example question. Provides context for when to use (side-by-side comparison) but does not explicitly mention when not to use or name alternative tools for other scenarios.

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 safe, idempotent, read-only behavior. The description adds significant behavioral context: it fans out across external APIs, explains partial failures (bundlephobia timeout with sources_failed), and notes measurement delays (5-30s). No contradictions with annotations.

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

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

The description is well-structured and front-loaded: starts with core purpose, then explains output components, ecosystem limitations, and failure behavior. Every sentence provides essential information without redundancy.

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

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

No output schema is provided, but the description thoroughly explains the return value (summary block fields, per-advisory detail, links, alternative versions). It also covers edge cases like partial failures and ecosystem scope, making it complete for an agent to understand and invoke the tool.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds value by clarifying that the version defaults to the latest when omitted, which is not explicit in the schema description. However, it repeats the scoped package acceptance from 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?

Description clearly defines the tool as a composite check for evaluating npm packages, covering license, advisories, bundle size, etc. It specifies the ecosystem (NPM only) and distinguishes from siblings by being a dedicated dependency scanner, which none of the siblings appear to be.

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 ('is X safe / popular / small' or 'what does adding lodash cost me') and provides alternatives for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). Also warns about partial failures and timing.

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. The description adds that it returns metadata (name, summary, etc.) and a URL for follow-up tools. It does not contradict annotations and provides useful behavioral context beyond what annotations offer.

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 long, front-loaded with the action and resource, and includes essential return information. No verbose or redundant wording.

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

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

The tool has 3 parameters and no output schema, but the description explains return values (name, summary, etc.) and links to sibling tools. It could mention handling of no results or pagination, but the limit parameter addresses pagination implicitly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning: it elaborates that 'query' is keywords and that 'org_id' is optional. This is already covered by the schema descriptions.

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

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

The description clearly states the verb 'Search', the resource 'City of Seattle GIS open geospatial datasets', and provides examples (parcels, zoning, etc.). It also mentions returning a URL for use with sibling tools query_layer/layer_info, distinguishing it from other tools.

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

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

The description implicitly tells the agent to use this tool to find datasets and then pass the returned URL to query_layer or layer_info for further queries. It does not explicitly state when not to use it or list alternatives, 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?

The description discloses the embedding model (BGE-base-en), windowing (500-char overlapping), token limit (200K chars with truncation flag), and output specifics (top-N passages with offsets and similarity scores). Annotations already convey readOnly, idempotent, and non-destructive nature, and the description adds 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 and front-loaded with core purpose, then usage context, then technical details. All sentences are substantive, though the technical details (model, windowing, char cap) could be slightly more integrated with the main narrative. Still, it's 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?

Despite lacking an output schema, the description explains return format (passages with offsets and scores) and technical constraints (model, windowing, char limit). It could mention idempotency (already in annotations) or error cases, but for a search tool it is reasonably complete.

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

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

Schema coverage is 100%, but the description adds meaningful examples for each parameter: 'text' as 'SEC 10-K body', 'query' as natural-language questions ('supply-chain risk'), and 'limit' with range (1-20). This enriches understanding 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 performs semantic search inside a fetched record, using specific verb+resource ('search within a source'). It distinguishes from sibling tools like 'search_datasets' and pairs with 'ask_pipeworx_grounded', making its unique role evident.

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

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

The description explicitly advises when to use ('when the record is too big to cram into the prompt') and mentions a complementary tool ('ask_pipeworx_grounded'). It implicitly discourages use on small texts. While it doesn't enumerate all alternatives, the guidance is clear and actionable.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds that it requires OAuth, explains per-type behavior, and details delivery channel mechanics (e.g., webhook signing secret returned once). There is no contradiction with annotations.

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

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

Description is well-structured: purpose, requirements, types with examples, delivery channels. Each sentence adds value. Could be slightly more concise but remains clear and organized.

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 (3 parameters, nested objects, no output schema), the description provides a complete picture: return value, authentication requirement, type-specific filters, and delivery options with limitations. The agent has enough context to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value beyond the schema: concrete examples for each type parameter, constraints on delivery fields (phone verification, SMS cap, webhook secret one-time), and clarifications like 'sponsor or condition required' for clinical trials.

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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This provides a specific verb (create) and resource (subscription), and the return value. Distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

Mentions required OAuth account and that anonymous/BYO cannot persist. Lists supported types and delivery channels. While it doesn't explicitly say 'use this when you need a subscription', the context makes it clear. It also provides restrictions (e.g., SMS cap, phone verification) that guide correct usage.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive. Description adds context: returns example questions with tool+argument shapes from a live catalog, and explains behavior with/without arguments.

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 front-loaded with alternative phrasings and well-structured, but slightly verbose with the list of example topics. Each sentence adds value, so it's efficient but not perfectly concise.

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

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

For a simple onboarding tool with no required params and no output schema, the description covers purpose, usage, and expected output completely. No gaps given the low complexity.

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

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

Schema coverage is 100% with clear description of the optional topic parameter. The description marginally adds value by explaining the effect of omitting topic and listing focus areas, but baseline 3 is appropriate as schema already does heavy lifting.

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

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

The description clearly states the tool as the onboarding entry point for new agents, providing example questions and tool calls. It distinguishes itself from siblings like ask_pipeworx by focusing on exploration rather than direct questioning.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It also provides guidance on alternatives (meta-tools) and when to omit or specify the topic parameter.

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 idempotent, non-destructive, and write operations. The description adds key behavioral details: ownership enforcement, deactivation instead of deletion, and that deactivated subscriptions still appear in `recent_alerts`. This significantly enhances understanding beyond annotations.

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

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

Three concise sentences: first states action, second enforces ownership, third explains data lifecycle. Every sentence adds non-redundant information. 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 single-parameter mutation tool with no output schema, the description covers what it does (cancel), constraint (ownership), data impact (deactivation, not deletion), and linkage to post-cancellation queries (`recent_alerts`). It is complete for the tool's complexity.

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

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

Schema coverage is 100% for the single required parameter `id`. The description adds that the id is a 'uuid returned by subscribe', linking it to a sibling tool and clarifying its origin. This adds meaning beyond the schema's type and 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 starts with 'Cancel a subscription by id', which is a specific verb+resource pair. It further distinguishes from sibling tools like `subscribe`, `list_subscriptions`, and `recent_alerts` by detailing ownership enforcement and deactivation behavior.

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

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

The description clearly states ownership enforcement ('you can only cancel your own subscriptions'), which guides when to use the tool. It also explains the deactivation effect and references `recent_alerts` for historical events, providing context but no explicit when-not 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, idempotentHint, openWorldHint, and destructiveHint=false. The description adds rich behavioral context: it explains the return format (verdict types, extracted structure, actual value with citation, percent delta), the data source (SEC EDGAR + XBRL), and that it replaces 4–6 sequential calls. No contradictions with annotations.

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

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

The description is a single paragraph that efficiently front-loads examples and usage, then explains scope and returns. Every sentence contributes value. Slight lack of structure (e.g., bullet points) but still concise and clear.

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

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

Given no output schema, the description fully explains the return values (verdict types, structured form, citation, delta). It also covers the data source and domain limitations. For a single-parameter tool with rich annotations, this is complete and sufficient 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?

There is only one parameter ('claim') with 100% schema description coverage. The schema already explains it is a natural-language claim string. The description reinforces this with examples, but does not add substantial new 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 specifies the tool's purpose: verifying natural-language factual claims against authoritative sources. It provides specific examples ('Is it true that...', 'fact check') and explicitly states the scope (company-financial claims). This distinguishes it from sibling tools by detailing its specialized function.

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

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

The description gives clear usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also limits the domain to company-financial claims. However, it does not explicitly mention when _not_ to use it or provide direct comparisons to sibling tools, though the domain specificity implies boundaries.

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