Arcgis Albuquerque

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's main contribution is contextual: default model, BYO key for Anthropic, and return structure (per-model score/confidence/signals/raw_response + combined view). This adds useful behavioral context beyond annotations.

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

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

The description is a single paragraph but well-structured, starting with purpose, then parameter details, then output format, then use cases. Every sentence adds value, though it could be broken into shorter segments for easier scanning.

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

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

With 4 parameters, 100% schema coverage, and no output schema, the description fully covers output structure (per-model fields + combined view) and gives example entity inputs. It is comprehensive for a probing tool with clear annotations.

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

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

Schema coverage is 100%, but the description adds meaning: default model behavior, context parameter purpose ('helps disambiguate common names'), and that _apiKey is passed through to Anthropic. This enhances understanding beyond the schema alone.

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

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

The description uses specific verbs ('probe', 'score') and identifies the resource ('LLMs for a business/brand/product/topic') and output ('visibility (0-100) per model'). It clearly distinguishes from sibling research tools by focusing on AI visibility scoring for marketing audits.

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

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

The description explicitly states use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and notes that Anthropic probing requires a BYO API key. It provides guidance on default behavior (omit models for just workers-ai) but doesn't explicitly contrast with alternatives like scan_competitor_ai_presence or deep_research.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true; description adds it returns structured answers with citation URIs, routes to many tools, and works on every tier—providing useful behavioral context beyond annotations.

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

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

The description is front-loaded with the key instruction, structured with clear sections (prefer, start here, step up), and every sentence adds value despite being lengthy 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?

No output schema exists, but description explains return format (structured answer with citation URIs) and covers usage, examples, and differentiation from alternatives, making it complete for the tool's purpose.

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

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

Schema coverage is 100% with clear parameter description and aliases listed; description adds value by providing diverse examples of questions, which helps the agent understand the expected input format.

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

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

The description clearly states that the tool routes questions to thousands of verified sources and returns structured answers with citations, distinguishing it from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', and describes when to step up to alternatives for hallucination-resistant answers or broad multi-part queries, providing clear context and exclusions.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. Description adds significant context: routing across 4,552 tools, argument filling, data fetching, extraction logic, and detailed refusal reasons. No contradictions.

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

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

Description is well-structured and detailed, but slightly longer than necessary. Every sentence adds value, though some redundancy exists (e.g., listing refusal reasons twice). Still efficient.

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

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

Despite no output schema, the description fully explains the return format (success and refusal) with all fields. Context includes routing, cost, and usage guidelines. 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% (all parameters described). Description simply says 'Your question in natural language' and lists aliases, adding minimal extra meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It explains the process (routing, fetching, extracting) and distinguishes it from sibling ask_pipeworx by mentioning the extra LLM call and refusal 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?

Explicitly guides when to use: 'Use whenever an answer will be quoted, cited, or acted on...' and when not: 'prefer ask_pipeworx for casual lookups.' Also mentions cost considerations.

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 show readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description goes far beyond these, detailing fan-out behavior, response shapes, resolver contract, parent_event extractor, news fallback, safety measures, and resolution-rule risk. Completely transparent.

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

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

The description is extremely verbose (multiple paragraphs with extensive examples). While well-structured, it is not concise and includes redundant details. A shorter, front-loaded summary would serve better for quick agent understanding.

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 (many classifiers, sources, edge cases), the description covers all necessary aspects: input flexibility, fan-out logic, response structure, safety blocking, and resolution rule risk. No output schema, but return values are thoroughly explained.

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

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

Schema coverage is 100% with all three parameters described. The description adds meaningful context: explains market input flexibility, depth enum meaning, and include_raw purpose. This adds value 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 states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' and specifies the input types (slug, URL, question text). It clearly distinguishes from sibling tools like polymarket_edges by focusing on research data gathering.

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

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

Explicit use cases are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also advises inspecting market_match_confidence before trusting analysis and mentions when the tool short-circuits (low confidence, closed markets). Does not explicitly list alternative tools but provides sufficient context.

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

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

Directly adds behavioral traits beyond annotations: explains data freshness (latest 10-K), off-calendar fiscal year handling, result sorting by primary metric, and citation URIs as output. No contradictions with annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false).

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

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

Description is front-loaded with common use case phrases and efficiently packed with information. Slightly verbose but each sentence adds value (e.g., 'Replaces 8–15 sequential lookups'). Could trim some examples but overall well-structured.

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

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

Covers entity types, data sources, sorting, and citation URIs. No output schema, but description outlines return format. Missing details on pagination, error handling, or rate limits, but given max 5 items these are minor gaps. Completeness is high.

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

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

Schema coverage is 100%, but description adds substantial meaning: defines 'company' vs 'drug' types with data sources, and for 'values' specifies ticker/CIK format for companies and name format for drugs, plus the 2-5 item range. This 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 specifies the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific verbs like 'compare', 'vs', 'versus', 'rank', and 'head to head'. It clearly distinguishes from sequential lookups by stating 'ALWAYS PREFER over sequential single-pack lookups', and lists concrete data sources (SEC EDGAR, FAERS).

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 usage triggers like 'Compare X and Y', 'X vs Y', and preference over sequential lookups. Does not include explicit when-not-to-use or alternatives, but the context is clear with sibling tools like 'entity_profile' for single entity lookups.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: account sign-in needed, response time (15-60s), return structure (findings packet with gaps[]), and explicit mention that it is not open-web search. No contradictions with annotations.

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

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

The description is somewhat lengthy but well-structured: front-loaded with critical account info, then detailed behavior, examples, and exclusions. Every sentence adds value, though a minor trim could improve conciseness without losing clarity.

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

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

Given 2 params, 100% schema coverage, rich annotations, and no output schema, the description is comprehensive. It covers prerequisites, usage scenarios, limitations, expected output, and timing, making it fully informative for an AI agent.

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

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

Schema coverage is 100%, with both parameters documented. The description adds meaning by explaining the depth enum values (quick=3, standard=5, thorough=8) and noting that broad/multi-part questions are acceptable. This exceeds the schema alone.

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

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

The description clearly states the tool's purpose: grounded multi-source research across structured data, decomposing questions into facets and routing to tools in parallel. It distinguishes itself from sibling tools like ask_pipeworx by specifying its scope (structured data vs. live news) and behavior (multi-faceted parallel 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 provides when-to-use and when-not-to-use guidance: recommends ask_pipeworx for single lookups or breaking news, and states account requirements (free sign-in, paid for 'thorough' depth). This helps the agent select the correct 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=true and idempotentHint=true. Description adds that results include full schemas with curated examples and are ready to call, no second lookup needed, which provides useful behavioral context beyond annotations.

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

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

Description is concise, front-loaded with purpose, lists domains, details return value, and ends with usage guidance. Every sentence is necessary and well-structured.

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

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

Given no output schema, the description adequately explains that results include names, descriptions, schemas with examples, and are directly callable. Could mention ordering or pagination, but not essential.

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

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

Schema coverage is 100% so baseline is 3. Description adds alias information for query parameter and limit constraints (default 20, max 50), enhancing clarity 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 'Find tools by describing the data or task' and lists specific domains (SEC filings, financials, etc.), differentiating it from sibling tools which are task-specific.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', providing a clear when-to-use and implying when not to (when you already know the tool).

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds critical behavioral details like 'soft-fails until reactivated' for patents and explains fan-out across multiple APIs, which enriches transparency 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 a single dense paragraph but efficiently packs essential information, front-loading example queries. It could be slightly more structured (bullet points), but every sentence adds unique value, earning a 4.

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 adequately explains all return fields (CIK, filings with URIs, fundamentals sorted, patents with note, news, LEI). For a multi-source tool with limited schema, this provides complete context for an agent to understand expected output.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by clarifying that 'type' is currently only 'company' and that 'value' must be ticker or zero-padded CIK, and explicitly warns names are not supported. This goes beyond the schema, justifying a 4.

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

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

The description explicitly states the tool creates a 'full cross-source profile of a US public company' and lists specific data sources (SEC, XBRL, USPTO, news, GLEIF) and return fields. It distinguishes itself from siblings like 'resolve_entity' by noting that names are not supported.

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 usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also tells when not to use (only have a name) and directs to 'resolve_entity' first. Includes example queries to illustrate intent.

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 confirms destructive nature ('Delete') and adds context about clearing sensitive data, 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?

Two succinct sentences. First sentence states action and resource; second provides usage context. No fluff, 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?

For a simple one-parameter tool with no output schema, description covers purpose, usage, and pairing instructions. No gaps given the low complexity and good annotation coverage.

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 for 'key'. The description restates 'by key' but adds no new meaning beyond the schema. Baseline 3 applies per guidelines.

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?

Clear verb 'Delete' and resource 'memory by key'. Explicitly states the tool's function and distinguishes it from siblings like 'remember' (store) and 'recall' (retrieve), which are mentioned.

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 specific scenarios: stale context, task completion, clearing sensitive data. Explicitly suggests pairing with 'remember' and 'recall', offering clear guidance on when and with which tools to use this.

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 (readOnlyHint, idempotentHint, openWorldHint) already convey safety and idempotency. Description adds behavioral detail: fetches page, extracts title/description/key links, outputs markdown ready for deployment. 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 sentences, front-loaded with core action and output format. 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 params and no output schema, description explains output (single text blob, path suggestion) and links parameters to use cases. Missing info like error handling, but adequate for tool 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 covers both parameters (url, max_links) with descriptions. Description mentions 'url' implicitly but doesn't add usage context beyond 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?

Description clearly states the tool generates an llms.txt file for a URL, using specific verbs like 'fetches', 'extracts', 'emits'. It distinguishes itself from siblings (none similar) by focusing on AI crawler indexing. No ambiguity.

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

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

Description lists practical use cases: getting a client's site indexed, drafting for own project, auditing competitors. Though it doesn't explicitly say when not to use it, the specific scenarios provide clear guidance.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds detail on the returned schema components, which is useful for understanding the tool's output. 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 a single, well-structured sentence that efficiently conveys the tool's purpose and output 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 tool's simplicity (one parameter, no output schema), the description adequately covers its functionality. It could mention error handling or prerequisites, but this is not critical.

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

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

The description restates the 'url' parameter and provides an example format, adding value beyond the input schema's description. With 100% schema coverage, this is above baseline.

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

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

The description clearly states the tool obtains an ArcGIS Feature/Map Service layer's schema by URL, specifying the returned information (fields, geometry type, record count, capabilities). This distinguishes it from sibling tools like query_layer.

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 the tool is for schema retrieval but does not explicitly state when to use it versus alternatives (e.g., query_layer). No exclusion criteria or usage 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=true and idempotentHint=true, so safety profile is clear. Description adds return fields but lacks details on pagination or limits.

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

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

Two focused sentences: first states purpose and output, second gives usage guidance. No redundant information.

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

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

Explains return fields and usage context adequately. Lacks mention of empty results or pagination, but sufficient for a simple list tool with annotations.

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

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

Schema coverage 100% with parameter already described. Description lists return fields but adds no extra meaning to the parameter itself. Baseline 3 is appropriate.

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

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

Clearly states 'List the caller's active subscriptions', specifying verb and resource. Distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing.

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

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

Explicitly advises use before adding more subscriptions or to find an id for cancellation. Provides clear context but no exclusions 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?

Adds meaningful context beyond annotations: the team reads digests daily, feedback impacts roadmap, rate limited to 5 per identifier per day, and free (no quota). No contradiction with annotations (destructiveHint=false, readOnlyHint=false, etc.).

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

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

Compact paragraph front-loading purpose, then usage scenarios, then instructions, then behavioral notes. Every sentence adds value with no redundancy.

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

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

Covers all key aspects: purpose, when to use, what to include, team behavior, rate limits. No output schema needed; description is self-contained for a feedback tool. Slight gap: does not mention response format, but that is standard for feedback.

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. The description reinforces the meaning of the 'type' enum and adds usage advice (e.g., 'be specific'). While schema already provides good semantics, the description adds extra value by clarifying expectations.

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

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

The description clearly states the tool is for sending feedback about bugs, missing features, data gaps, or praise. It uses specific verbs ('tell', 'broken, missing, or needs to exist') and distinguishes itself from sibling tools by focusing on feedback.

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

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

Explicitly enumerates when to use each feedback type (bug, feature, data_gap, praise) and provides specific instructions not to paste end-user prompts but to describe in terms of Pipeworx tools. Also mentions rate limits and cost, guiding appropriate use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h), and the aggregated data format. This goes beyond the annotations without contradicting them.

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

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

The description is concise, front-loaded with the main function, and despite being a single paragraph, it packs a lot of useful information without excess words. It could be slightly more structured (e.g., bullet lists), but it's efficient.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, behavioral traits (caching, privacy), and use cases. It is fully adequate for an agent to understand and invoke the tool correctly.

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

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

The schema covers 100% of parameters with a description explaining the window options. The tool description adds minimal extra value—it repeats the window choices and ties them to use cases, but the schema already does the heavy lifting. 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 returns top tools, top packs, and total call volume over a configurable window. It uses specific verbs and resources, and the function is distinct 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?

The description lists three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use cases). While it doesn't specify when not to use it or name alternatives, the use cases are clear and helpful for choosing the tool.

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

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

Annotations already indicate readOnlyHint, idempotentHint, etc. The description adds extensive behavioral context: scan logic, semantic anchor (Jaccard similarity), partition filter, fill check against CLOB depth, and trade recommendations. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with the core purpose, but it is somewhat lengthy due to detailed technical explanations. Every sentence adds value, but a slightly more concise version could be written without losing key information.

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

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

Given the tool's complexity and lack of output schema, the description adequately explains return values (opportunities[], partition_check, fill_check) and key concepts. It references sibling tools and covers edge cases, making it complete for agent understanding.

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

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

Both parameters in the input schema have descriptions (100% coverage). The tool description adds further detail, including example slugs and explanations of event vs topic modes, making the parameters' semantics very clear.

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 uses specific verbs and resources, and distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly explains when to use each mode (no args for trending_scan, event for single-event, topic for cross-event) and provides clear examples. It also references polymarket_fill_risk for custom sizing, guiding agents on alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true, indicating safe, read-only behavior. The description goes far beyond by detailing model families, response segments, diagnostics, caching, and edge calculation. There is no contradiction; it adds extensive context that helps the agent understand the tool's behavior precisely.

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

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

The description is very dense and long, which may overwhelm an AI agent. While it is structured into sections and front-loads the purpose, it contains excessive detail that could be condensed. For example, the model descriptions and algorithm details are thorough but could be shortened without losing essential guidance.

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

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

Given the complexity of the tool (9 parameters, multiple model families, no output schema), the description compensates by detailing the response structure, diagnostics, and caching behavior. It explains return segments and why certain data might be missing. This makes the tool self-contained for an agent to invoke correctly.

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

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

The schema covers all 9 parameters with descriptions. The tool description adds extra meaning, e.g., explaining slippage_pp in context of Polymarket fees, and clarifying that min_partition_leg_kelly applies to per-leg Kelly instead of min_kelly. This adds value beyond the schema.

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

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

The description clearly states the tool performs a scan of Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It explicitly says it's built for 'what should I bet on today' and distinguishes itself from paging markets. The verb 'scan' and resource 'Polymarket markets' are specific, and the purpose is distinct from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description explains when to use the tool (for daily betting discovery) and mentions caching and knobs for customization. However, it does not explicitly state when not to use it or provide alternatives. The sibling tools list helps, but the description itself lacks exclusion criteria.

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 the annotations (readOnlyHint, idempotentHint). It explains that snapshots are written on cache-miss, gaps in data mean nobody scanned that day, and decay numbers come from daily closes. There is no contradiction with annotations.

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

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

The description is efficiently structured: it starts with the core question, then details response fields, and ends with limits. Every sentence provides value without redundancy. It is front-loaded and easy to parse.

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

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

Despite no output schema, the description fully covers the response structure (tracked[], expired[], snapshot_dates[]) and explains each field's content and derivation. It also mentions data limitations (TTL, snapshot start). For a tool of this complexity, this is comprehensive.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by explaining 'days' as lookback with default and clamp, and 'window' as snapshot family with examples (24hr, 1wk, 1mo). It provides context that helps understand the parameters beyond the schema.

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

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

The description clearly states that the tool provides edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?'. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical time-series and trends rather than just current edges.

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

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

The description gives explicit context: a fresh wide edge and a 3-week-old wide edge are different trades, implying use for assessing edge persistence before trading. It mentions limits like 60-day TTL and snapshot gaps, providing good guidance on when to use, though it doesn't explicitly state when not to use.

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

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

The description adds significant behavioral details beyond annotations (readOnlyHint, idempotentHint, etc.): it walks the ladder, returns a verdict (clean|degraded|cannot_fill), provides per-leg fill detail for baskets, and warns about forced directional risk. No contradiction with annotations.

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

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

The description is thorough and front-loaded with the core purpose. Every sentence adds value, but it is relatively long. Given the complexity of dual modes and detailed returns, it is justified; however, it could be slightly more concise without losing critical information.

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

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

With no output schema, the description compensates by listing all return fields for both modes. It covers error states (cannot_fill), explains the mutual exclusivity of market/event, and provides real-world context for when partial fills are risky. The only minor gap is not explicitly stating that market and event are mutually exclusive, but that is implied.

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

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

Schema description coverage is 100%, but the description adds extensive meaning: explains how size_usd differs between single-market (spend/proceeds) and basket (settlement notional), default side logic for basket, and the interplay between market and event parameters. 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's purpose: checking realizable vs theoretical edge against live CLOB order-book depth. It distinguishes between single-market and basket modes and lists specific return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), making the purpose unambiguous and distinct from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly tells when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround on thin books is not capturable, partial basket fills create unhedged directional risk), providing clear context and exclusion criteria.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant value beyond annotations by detailing compatibility_warning conditions, temporal_alignment checks, and when spreads are meaningless. 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 with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. It is informative but somewhat verbose; minor trimming could improve conciseness without losing clarity.

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

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

Given the tool's complexity (multiple modes, safety conditions, no output schema), the description thoroughly explains behavior, return fields (including top_spreads_pp, compatibility_warning, temporal_alignment), and caveats. 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% with each parameter having a description. The description adds useful context: listing the 10 topic shortcuts, explaining that explicit parameters override mapped ones, and clarifying the relationship between topic and explicit IDs. This enhances understanding beyond the schema alone.

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

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

The description clearly defines the tool's purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison for identical outcomes, with explicit details on modes and safety fields.

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

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

The description explains two modes (topic shortcuts and explicit parameters), provides guidance on interpreting compatibility_warning and temporal_alignment, and warns that most pre-mapped topics are not tradeable. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage or polymarket_edges, so some usage context is implied rather than stated.

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

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

Annotations already declare readOnly and idempotent. The description adds behavioral details: returns attribute rows and geometry, and uses SQL-like syntax, which goes 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?

Two sentences: first defines purpose and parameters, second gives a practical tip. No unnecessary words, front-loaded with key info.

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

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

For a query tool with full schema coverage and no output schema, the description covers expected behavior (rows+geometry) and provides a starting example. Lacks mention of return format but sufficient for selection.

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

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

Schema covers all parameters (100%). Description adds value by explaining SQL-like 'where', comma-separated 'out_fields', and providing a sample usage, enhancing understanding beyond schema 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 clearly states it queries an ArcGIS layer by URL, specifies the SQL-like syntax and parameters, and distinguishes from sibling tools like search_datasets by indicating the URL source and query nature.

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?

Includes a concrete usage example ('where="1=1" + out_fields="*" to sample') and implies the tool is for querying layers whose URLs come from search_datasets. However, it does not explicitly list when not to use or compare to alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable context about scoping (anonymous IP, BYO key hash, account ID) and the pairing with remember/forget, going well beyond the annotations.

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

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

Three sentences, front-loaded with the core purpose, then use cases and scope. No unnecessary words. Every sentence adds value.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, scope, and related tools. It is complete and leaves no obvious gaps.

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

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

Schema coverage is 100% and the description does not add details beyond what the schema provides. The baseline of 3 is appropriate as the description reinforces the parameter's behavior but does not add new semantic meaning.

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 ('retrieve' or 'list') and the resource (previously saved memory keys). It distinguishes itself from sibling tools like 'remember' and 'forget' by explicitly mentioning them.

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

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

The description explains when to use the tool ('look up context the agent stored earlier') and provides guidance on omitting the key to list all. It does not explicitly state when not to use, 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 adds significant value beyond annotations: it explains return content (source, citation_uri, payload), the mark_read side effect (flags events read, affecting subsequent calls), and polling safety. Annotations only provide hints, but the description fleshes out behavior.

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

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

The description is three sentences long, front-loaded with purpose, and each sentence earns its place: purpose, return details, filtering/side effect/alternative access. No fluff, efficient 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 5 optional parameters and no output schema, the description covers input filtering, return structure, mark_read side effect, and alternative access. It lacks details on pagination, error handling, or authentication, but for a read tool with rich annotations, it is fairly complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful context for mark_read, explaining its consequence beyond the schema's 'Flag the returned events read'. It also mentions type and since for filtering, though those are already in schema. Overall, it enhances understanding.

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

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

The description clearly states 'Pull fired events from your subscription feed', specifying the verb (pull) and resource (alerts from subscription feed). It details what each alert carries and offers filtering options, distinguishing it from sibling tools like list_subscriptions or subscribe.

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 usage context: it describes filtering by type and since, and explains the mark_read parameter's effect. It also mentions polling suitability and an alternative REST endpoint for scripts/dashboards, but lacks explicit comparisons to other tools like recent_changes or search_within.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses parallel fan-out to multiple sources, fallback logic, partial failure for USPTO, and output structure (changes grouped by source, total_changes, citation URIs). No contradictions.

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

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

Description is front-loaded with purpose and examples, but packs extensive detail into a single paragraph. Dense but not verbose; slightly long but each sentence adds value. Could be broken into shorter sentences but highly efficient.

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

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

Given no output schema, the description specifies the return format (structured changes[] grouped by source + total_changes count + pipeworx:// URIs). Covers all inputs, behaviors, and edge cases (fallback, partial failure). Complete for a complex multi-source 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 has 100% coverage, but description adds value: explains 'since' accepts ISO date or relative shorthand with typical monitoring suggestion ('30d' or '1m'), clarifies 'value' can be ticker or CIK, and 'type' is only 'company'. Adds practical usage guidance beyond schema.

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

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

The description clearly states it provides a change feed for a company over a time window, listing specific sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly distinguishes from entity_profile for static profiles. The verb 'change feed' and resource 'company' are precise.

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 examples ('What's new with X', 'latest on Y') and a clear when-not-to-use directive ('Use entity_profile instead when you want the static profile'). Also notes fallback behavior (GDELT preferred, GNews when rate-limited).

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, including key-value storage, scoping by identifier, and persistence details (persistent for authenticated users, 24 hours for anonymous). No contradictions with annotations (idempotentHint=true, destructiveHint=false).

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

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

The description is concise, with the main purpose in the first sentence, followed by usage guidance, storage details, and pairing information. Every sentence adds value 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 tool's simplicity (key-value store with no output schema), the description completely addresses when to use, how it works, scope, and integration with sibling tools. No missing information.

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

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

The input schema has 100% schema description coverage, so baseline is 3. The description adds value by providing example key patterns ('subject_property', 'target_ticker', 'user_preference') and explaining that value is any text, which enhances 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 verb 'Save' and the resource 'data needed later', specifying the scope across conversations and sessions. It distinguishes the tool from siblings like 'recall' and 'forget', which are mentioned in context.

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

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

The description explicitly tells when to use the tool ('when you discover something worth carrying forward') and provides concrete examples. It mentions pairing with 'recall' and 'forget', though it does not explicitly state when not to use it.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already indicate safe, non-destructive behavior. The description adds value by noting internal cascading ('replaces 2-3 manual lookups') and auto-disambiguation for companies, which informs the agent about potential latency or complexity.

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 well-structured paragraph with front-loaded examples and no redundant sentences. Every sentence adds essential context, making it efficient and easy to parse.

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

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

Covers purpose, types, return values, and internal behavior. Missing details like error handling or rate limits, but given the presence of annotations (readOnlyHint, etc.) and the nature of a lookup tool, it is sufficiently complete for an agent to use effectively.

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

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

Schema coverage is 100%, and the description significantly enriches parameter meaning. For 'value,' it provides concrete examples and return details (e.g., ticker + CIK + company name + citation URI). For 'type,' it explains what each enum value entails, far exceeding the schema's minimal 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 resolves names to canonical identifiers, with specific examples ('ticker', 'CIK', 'RxCUI') and distinguishes it as the first step for such queries. Supported types (company, drug) and their return fields are detailed, leaving no ambiguity about what the tool does.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It does not mention when not to use or list alternatives, but the context is strong enough for an agent to determine appropriateness.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral context: it calls ai_visibility_check for each entity, ranks results, and returns specific fields (score, confidence, signal density). No contradiction with annotations.

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

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

Two sentences plus a parenthetical and a 'Returns' clause. Front-loaded with main purpose. Every part adds value, though slightly wordy in the parenthetical. 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 specifies returned structure (ranked list with score, confidence, signal density). Given 4 params and no nested objects, the description covers the essential behavior and output. Could detail ranking criteria more, but sufficient.

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

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

Schema coverage is 100%, but description adds beyond schema: notes first entity is treated as 'subject' for narrative, context disambiguates common names, models can be omitted for default workers-ai, and _apiKey is only needed if using anthropic model. This extra guidance is valuable.

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

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

Clearly states it compares AI visibility across multiple entities, probes with ai_visibility_check, ranks by score, and surfaces most/least recognized. Distinguishes from sibling ai_visibility_check (single entity) and compare_entities (general comparison).

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 it is useful for competitive AI-marketing audits and gives an example question ('does Claude know about us as well as our competitors?'). Implicitly indicates when to use compared to single-entity probe, but does not explicitly mention when not to use.

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

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

Annotations already show readOnly, idempotent, non-destructive. Description adds key behavioral traits: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed will list timeouts. 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?

Description is somewhat long but each sentence adds value: composite nature, data sources, usage guidance, ecosystem limit, graceful failure. Front-loaded with key purpose. Loses a point for slight verbosity but overall efficient.

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

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

Given the complexity (multiple data sources, partial failures, default behavior), description covers all needed context. Returns summary details are listed, failure modes explained, version defaults clarified. No output schema but description sufficiently describes return structure.

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

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

Schema coverage is 100% so baseline is 3. Description adds value by noting scoped packages (e.g. '@types/node') are accepted and that version defaults to latest published. Provides meaningful extra context beyond schema.

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

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

The description clearly states it is a composite check for adding an npm package, covering license, advisories, version history, bundle size, dependency count, ESM/tree-shake support. It uses specific verbs like 'scan' and 'check' and distinguishes itself from siblings by focusing on npm packages.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also specifies it's NPM only, directing other ecosystems to deps.dev:version directly. Provides clear context for use and alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context by specifying the returned fields (name, summary, record_count, owner/org, url) and explaining how the url should be used downstream. 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 two sentences, front-loaded with purpose and examples, and contains no redundant information. It is highly concise and well-structured.

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

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

The description explains the return structure (fields and url usage) despite no output schema, and sets scope (City of Albuquerque GIS). It lacks mention of pagination or handling of large result sets, but is otherwise complete for a search 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 descriptions are provided for all parameters. The description does not add extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool searches for datasets by keyword, specifies examples (parcels, zoning, etc.), and details what each result includes (name, summary, record_count, owner/org, url). It distinguishes itself from sibling tools like query_layer and layer_info by explaining the returned url's purpose.

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

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

The description implies the tool is used before query_layer or layer_info, but does not explicitly state when to use this tool versus other siblings or provide exclusions. The usage context is implied but not formally guided.

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

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

Annotations already mark readOnlyHint, openWorldHint, idempotentHint as true. The description adds beyond annotations: technical details about BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. Full behavioral disclosure.

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

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

Description is concise at about 6 sentences, front-loaded with purpose and usage guideline, followed by technical details. No unnecessary words; every sentence adds value.

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

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

For a tool with no output schema, the description sufficiently explains return format (top-N passages with character offsets and similarity scores), technical constraints (model, window size, char limit), and context for pairing with sibling tool. Covers all essential aspects for correct invocation.

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

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

Schema description coverage is 100% for all 3 parameters, so baseline is 3. The description does not add new parameter-specific semantics beyond what the schema already provides, but it enriches understanding of the output (character offsets, similarity scores) which indirectly helps parameter usage.

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

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

The description clearly states it performs semantic search inside a fetched record, using specific verb 'search within'. It distinguishes from sibling tools like ask_pipeworx_grounded by explaining the pairing and scoping inside a record.

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 the record is too big to cram into the prompt') and provides an alternative sibling (ask_pipeworx_grounded) with clear pairing guidance ('fetch with the gateway, ground over the relevant passages').

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 the annotations: requires OAuth account, delivery channels have limitations (10/day SMS cap, webhook auto-disabled after 10 failures), and the signing secret is only returned once. The annotations readOnlyHint=false and idempotentHint=true are not contradicted, though the 'Create' action is typically non-idempotent, but the annotation is accepted as given.

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 packed with information but is somewhat lengthy. It front-loads the core purpose and return value, but the dense listing of subscription types and delivery options could be better structured (e.g., bullet points). Nonetheless, every sentence adds value.

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

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

Given the tool's complexity (3 parameters, nested objects, multiple types, no output schema), the description covers all essential behavioral aspects: requirements, type-specific filters, delivery channels with constraints, return value description, and error contexts (e.g., 10-run webhook failure). It is fully adequate for an agent to understand usage.

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

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

Schema coverage is 100%, yet the description provides extensive additional semantics: type-specific parameter structures with examples, delivery channel details beyond schema (e.g., webhook signing, auto-disabling), and validation rules (phone must be verified, HTTPS-only for webhook). This greatly enhances the schema's bare definitions.

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

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

The description clearly states the action ('Create a proactive monitoring subscription'), the resource ('live-data event stream'), and the return value ('new subscription id'). It distinguishes the tool from siblings such as 'list_subscriptions' and 'unsubscribe' by focusing on creation and monitoring.

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

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

The description provides clear context for when to use the tool, including subscription types, delivery channels, and prerequisites (Pipeworx OAuth account). It also notes limitations (anonymous/BYO cannot persist, SMS cap). However, it does not explicitly contrast with alternative tools or state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, so the tool's safety profile is clear. The description adds behavioral context by detailing what it returns (category-bucketed example questions with tool+argument shapes) and that it draws from a live catalog, 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 somewhat verbose with multiple example phrasings, but it is front-loaded with the core purpose and structured clearly. While every sentence adds value, a slightly more concise version could be crafted.

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 lack of an output schema, the description compensates by explaining the return format in detail: category-bucketed example questions with exact tool+argument shapes. It also covers the tool's role in learning about meta-tools, making it contextually complete for an onboarding tool.

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

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

Schema description coverage is 100%, so the schema itself documents the parameter. The description adds value by explaining the purpose of the 'topic' parameter with specific examples (finance, pharma) and notes that omitting it gives a cross-category spread, enhancing 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's purpose: an onboarding entry point for new users to understand what Pipeworx can do, returning example questions with tool calls. It uses specific verb 'suggest' and resource 'questions', and distinguishes from siblings like 'ask_pipeworx' and 'discover_tools'.

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

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

Explicitly states when to use this tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' Also explains when to pass the 'topic' argument vs. call with no arguments, providing clear context for 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 behavioral context beyond annotations by explaining the row is deactivated (not deleted), preserving historical events. Ownership enforcement is also disclosed. 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?

Two sentences provide complete information with no wasted words. Action is front-loaded ('Cancel a subscription by id').

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage, behavioral effects, and ownership constraints completely.

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

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

Schema coverage is 100% with a clear description for the single parameter 'id'. The tool description does not add extra meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb and resource, distinguishing it from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement, indicating when to use (own subscriptions only) and when not to (others' subscriptions), and explains the effect on historical events via recent_alerts.

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 non-destructive nature. The description adds behavioral context: returns verdict, structured form, actual value with citation, and percent delta, and notes efficiency gains. 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 synonyms and usage guidance, followed by technical details. Every sentence adds value, and there is no superfluous information. It is well-structured and efficient.

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

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

Given the single parameter and no output schema, the description covers purpose, usage, return format, domain, and efficiency. It is mostly complete, but could mention error handling or rate limits for full completeness.

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

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

Schema description coverage is 100% for the single parameter 'claim', with a brief description. The description adds value with examples and context about natural-language format, enhancing 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's purpose: natural-language claim verification against authoritative sources. It provides synonyms and examples, and distinguishes it from siblings as a specialized fact-checking tool for financial claims.

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

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

The description explicitly says to use when the agent needs to check factual correctness, and specifies the supported domain (company-financial claims for US public companies). It implies limitations (v1 scope) but does not explicitly mention alternatives or when not to use.

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