Arcgis Kansas

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

Beyond annotations (readOnly, idempotent, not destructive), the description adds that the default model is free (Workers AI Llama-3.3-70b), passing `_apiKey` enables paid Anthropic calls (BYO key), and returns per-model {score, confidence, signals, raw_response} plus a combined view. This covers cost, output structure, and external API calls effectively.

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 four sentences, front-loaded with the core purpose, then default behavior, output structure, and use cases. Every sentence adds essential information without redundancy.

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

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

For a tool with 4 well-described parameters and no output schema, the description sufficiently explains input usage (including optional parameters) and the return format (per-model details + combined view). It covers the main use cases and disambiguation need.

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

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

Schema coverage is 100%, and the description adds meaningful context: default model, the role of `_apiKey` to enable Anthropic, and `context` for disambiguation. This goes beyond the schema descriptions, though it does not detail every possible model or error behavior.

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

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

The description clearly states the verb 'probe' and the resource 'LLMs' for a specific outcome: score visibility (0-100) per model. It distinguishes the tool from siblings like 'ask_pipeworx' and 'scan_competitor_ai_presence' by focusing on multi-model visibility scoring for AI marketing audits.

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

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

The description provides usage contexts ('AI-marketing audits, pre-launch brand checks, competitive monitoring') but does not explicitly state when not to use this tool or compare it with alternatives. While the tool's uniqueness is implied, clearer exclusion criteria are absent.

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 substantial behavioral context beyond annotations: describes routing to 4,482 tools, argument filling, structured answer with pipeworx:// citation URIs, fast single-call execution, and tier availability. 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?

Well-structured with front-loaded key information and clear sections. Somewhat lengthy but every section adds value; could be slightly more concise.

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

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

Given the tool's complexity and lack of output schema, the description is highly complete: covers purpose, when to use, how it works, examples, and output format. No gaps for effective use.

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

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

Schema describes the question parameter and all aliases with 100% coverage. Description adds context on what types of questions to ask via examples and domains, but does not provide additional parameter-level details 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?

Explicitly states it routes questions to the right tool among 4,482 verified sources and returns structured answers with citations. Clearly distinguishes from siblings like web search, ask_pipeworx_grounded, and deep_research.

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

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

Provides extensive guidance: 'PREFER OVER WEB SEARCH', lists specific domains and question types, and explicitly states when to step up to grounded or deep_research. Includes examples and default entry point recommendation.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description details the exact process: routing, argument filling, data fetching, extraction, and refusal reasons. It also discloses the cost of an extra LLM call and the specific refusal reasons, adding substantial behavioral context.

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

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

The description is relatively long but every sentence provides useful information. It is front-loaded with the key purpose and then expands on details. No fluff, but could be slightly more concise. Score 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 lacking an output schema, the description thoroughly explains the return structure (answer, evidence, confidence, source, etc.) and all possible refusal reasons. It covers usage guidance, behavioral details, and parameter semantics, making it complete for an agent to invoke correctly.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by explaining that all six parameters are aliases for the question and that it accepts natural language, which is not evident from the schema alone. This helps the agent understand the flexibility.

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

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

The description clearly states the tool provides a hallucination-resistant answer mode for high-stakes reads, differentiating it from ask_pipeworx by specifying that it extracts answers only from tool results. It uses specific verbs and resources, making the purpose unambiguous.

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

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

The description explicitly advises when to use this tool (when answers will be quoted or acted on, for high-stakes reads) and when not to (prefer ask_pipeworx for casual lookups). It also notes the extra cost compared to ask_pipeworx, providing clear 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 goes beyond annotations (readOnly, idempotent) to detail the internal process: classification, fan-out, response shapes, safety mechanisms (low-confidence short-circuit, closed-market handling, wide-spread warning), and resolution-rule risk (cancellation_rule). This provides comprehensive behavioral transparency without contradicting annotations.

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

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

The description is lengthy but front-loaded with the core purpose. It includes many detailed examples and explanations, which adds value but reduces conciseness. The structure is logical, but the density may overwhelm some agents. Every sentence earns its place, but overall it could be more streamlined.

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

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

Given the tool's complexity (multiple classifiers, fan-outs, response shapes, safety mechanisms), the description is exceptionally complete. It covers all edge cases (closed markets, low confidence, wide spreads, cancellation rules) and explains return values in detail, compensating for the lack of an output schema.

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

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

All three parameters are fully described in the schema (100% coverage). The description repeats the schema's parameter descriptions without adding new semantics. Examples in the schema provide context, but the description does not enhance understanding beyond what the schema already offers.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet with Pipeworx data), and scope (comprehensive data pack). This differentiates it from sibling tools like polymarket_edges or polymarket_arbitrage, which focus on specific aspects.

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 provides use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives input examples and explains when the tool may return limited results (low confidence, closed markets, wide spreads). However, it does not explicitly state when NOT to use this tool versus alternatives like polymarket_edges.

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

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

Annotations already indicate a safe, non-destructive, idempotent read operation. The description adds valuable behavioral context: data sources (SEC EDGAR, FAERS), handling of off-calendar fiscal years, result sorting by primary metric, and return of paired data with citation URIs. 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 informative but somewhat lengthy. However, every sentence adds value (query examples, data details, sorting, return format, guidance). It is front-loaded with examples, making it easy to parse. Slightly verbose but not wasteful.

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

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

Given the tool's complexity (two entity types with different data) and lack of output schema, the description fairly completely covers what the agent needs: data sources, handling of fiscal years, sorting behavior, and return format (paired data + citation URIs). Missing some edge cases or error conditions, but adequate for selection and invocation.

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

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

Schema coverage is 100%, and the description adds substantial meaning. For 'type', it explains what data each enum value retrieves. For 'values', it specifies format (tickers/CIKs for company, drug names for drug) and provides examples. This enriches the schema beyond mere enum descriptions.

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

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

The description opens with concrete query examples ('Compare X and Y', 'X vs Y', etc.) and explicitly states it performs side-by-side comparison of 2–5 companies or drugs in one parallel call. It clearly distinguishes itself from sequential single-pack lookups, providing a specific verb and resource scope.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving a clear directive on when to use. It also provides use-case examples like 'which is bigger' and 'rank these companies', guiding the agent to choose this tool for comparisons over alternatives.

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

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

Beyond annotations (readOnly, idempotent, openWorld, not destructive), the description adds critical behavioral traits: account requirements, paid tier for thorough depth, 15-60s response time, returning gaps for unanswered facets, and warning about empty results for non-structured topics. This provides comprehensive transparency.

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

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

The description is relatively long but efficiently packed with essential information, front-loading the most critical points (account requirement, alternatives). Every sentence adds value, and the structure is logical. While not extremely concise, it is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (2 params, 29 siblings, no output schema), the description is remarkably complete: explains decomposition, parallel routing, findings packet structure, return format (verbatim evidence, confidence, source, fetched_at, citations, gaps), expected latency, account tiers, and failure mode for non-structured topics. It fully covers all relevant aspects.

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 adds meaning beyond the input schema by explaining the depth enum values (quick=3, standard=5, thorough=8) with paid plan requirement, and emphasizes that the question parameter supports broad/multi-part queries with automatic decomposition. Schema coverage is 100%, so baseline is 3; the extra context pushes it to 4.

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

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

The description clearly states the tool's purpose: grounded multi-source research across structured data sources, decomposing questions into facets, and returning a findings packet with evidence, confidence, source, and citations. It explicitly differentiates from sibling tools like ask_pipeworx.

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

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

The description provides explicit when-to-use guidance: best for broad/multi-part structured data questions, single lookups should use ask_pipeworx, breaking news should use ask_pipeworx, and usage requires sign-in with a free account (depth:thorough needs paid). It also mentions that topics not in structured catalog yield empty gaps, directing to ask_pipeworx for such cases.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds that results are ready to call directly with full schemas, and no second lookup needed. No contradiction. Minor omission: no mention of response size beyond limit param.

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 well-structured sentences, front-loaded with purpose and guidance, efficient use of bold for emphasis. No wasted words.

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

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

Given no output schema and high schema coverage, the description fully covers purpose, usage, return details, and call behavior. Sufficient for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions for all parameters. The description lists aliases but adds little 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?

The description clearly states the tool finds tools by describing data/task, using specific verbs like 'browse, search, look up, discover'. It distinguishes from sibling tools by positioning as a discovery-first step, contrasting with getting a single answer.

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: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Also provides context with domain list, implying when not to use (if 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) align well. Description adds details: parallel call, fanning across sources, specifics of returns (filings with URIs, fundamentals sorted, patents with caveat 'soft-fails until May 2025', news fallback). 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 information-dense but effectively front-loaded with example queries and guidance. Every sentence adds value, though slightly longer than minimal. Good structure.

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

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

Given the tool's complexity (multiple sources, returns), the description covers return fields, caveats (patents soft-fail), and example calls comprehensively. No output schema, so this completeness is essential and well-provided.

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

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

Schema coverage is 100% with descriptions for both parameters. Description reinforces and adds context (e.g., zero-padded CIK, names not supported), providing additional value beyond schema. Slightly above baseline 3.

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

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

The description clearly states the tool provides a full cross-source profile for US public companies, listing sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return fields. It distinguishes itself from sibling tools like resolve_entity by specifying when to use each, and emphasizes preference over chaining single-pack lookups.

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

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

Explicit guidance: use when user asks for holistic view of a US public company; always prefer over chaining; use resolve_entity if only have a name; names not supported. Clear when-not-to-use and alternatives 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 destructiveHint=true, so description reinforces this by stating 'Delete'. It adds context about clearing sensitive data, which is helpful but not beyond annotation coverage. No contradictions.

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

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

Two sentences with clear structure: first sentence states purpose, second provides usage guidance and sibling pairing. No extraneous words, highly efficient.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage context, and safety cues. Combined with annotations (destructive, idempotent), it is fully complete.

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

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

Schema coverage is 100% with one required 'key' parameter described as 'Memory key to delete'. The tool description does not add additional semantic detail beyond that, 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 verb 'Delete' and the resource 'memory by key'. It distinguishes itself from sibling tools 'remember' and 'recall' by explicitly pairing with them. This provides specific and differentiated 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 provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with 'remember' and 'recall', indicating companion tools. No explicit when-not-to-use, but positive guidance is strong.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. Description adds value by explaining the internal process ('fetches the page, extracts title/description/key links') and output format ('single text blob ready to drop at site-root/llms.txt'). No contradiction.

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

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

Two paragraphs with front-loaded purpose, efficient explanation, and clear usage examples. Every sentence contributes value.

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

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

With 2 simple parameters, rich annotations, and a clear description covering purpose, behavior, output, and use cases, the tool definition is fully sufficient for correct selection and invocation.

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

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

Schema coverage is 100% (both parameters have descriptions). The description does not add significant detail beyond the schema for the parameters; the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Generate') and resource ('production-ready llms.txt file') and clearly distinguishes from sibling tools by targeting a unique output format.

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

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

Description lists three concrete use cases ('getting a client's site indexed by AI', 'drafting llms.txt for your own project', 'auditing how an AI crawler would see a competitor') but does not specify when not to use or provide alternative tool references.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying the exact return items (fields, geometry type, record count, capabilities), which goes 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?

Single sentence that is front-loaded with the core purpose. No unnecessary words, every part of the description contributes meaning.

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

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

Given the tool's simplicity (one parameter, no output schema, strong annotations), the description fully covers what the tool does and what it returns. No gaps.

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

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

Schema description coverage is 100% and the parameter is well-described in the schema. The tool description does not add additional detail about the parameter, but it is sufficient. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb (Get), resource (ArcGIS Feature/Map Service layer's schema), and specifics (fields, geometry type, record count, capabilities). It distinguishes from sibling tools like query_layer which query data, not schema.

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

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

The description implies when to use it (to get layer schema), but does not explicitly mention when not to use it or alternatives. No exclusions or prerequisites are 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?

Beyond annotations (readOnlyHint, etc.), description adds that only active subscriptions are returned by default and discloses returned fields. No contradictions, but could mention pagination or rate limits if applicable.

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

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

Two concise sentences: first states purpose and output, second provides usage guidance. No unnecessary words.

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

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

For a simple read-only list tool with one optional param and no output schema, the description covers purpose, return format, usage context, and default behavior. Complete and sufficient.

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

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

Schema coverage is 100% for the single parameter include_inactive, and description does not add extra meaning beyond the schema. Baseline of 3 is appropriate.

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

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

Description clearly states 'List the caller's active subscriptions' and specifies return fields. It explicitly distinguishes from sibling tools like subscribe and unsubscribe by noting its use for reviewing before adding or finding an id to cancel.

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

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

Explicitly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Does not mention when not to use, but context with sibling tools 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?

Description adds behavioral context beyond annotations: rate-limited to 5 per identifier per day, free, and doesn't count against tool-call quota. No contradiction with annotations which are all 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?

Information is front-loaded with purpose and usage guidelines. Every sentence is useful but could be slightly more concise. Overall well-structured.

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

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

Given 3 parameters (2 required, nested objects, no output schema), the description provides complete guidance: what to include, how to frame feedback, constraints, and usage notes. 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?

Schema covers all 3 parameters with descriptions (100% coverage). Description does not add significant extra meaning to parameter semantics beyond reinforcing the feedback types and context structure.

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 (broken, missing, needs to exist) to the Pipeworx team. It specifies four feedback types (bug, feature, data_gap, praise) and distinguishes itself from siblings which are unrelated to 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?

Explicit guidance on when to use each feedback type: bug for wrong/stale data, feature for missing tools, data_gap for missing data, praise for good experiences. Also advises against pasting end-user prompts and notes rate limits and quota exemption.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable transparency: data source (CF analytics-engine), no PII, and caching behavior (5min-1h). No contradictions.

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

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

The description is concise, with the main purpose front-loaded, followed by use cases and technical details. 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?

No output schema, but the description clearly states what is returned (top tools, top packs, total call volume) and the data characteristics. It is sufficient for a simple aggregation tool, though more precise formatting details could be added.

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 enum and description. The description adds behavioral context for the window parameter ('shorter windows surface what's hot right now; longer windows show steady-state demand'), which enriches the meaning beyond the schema.

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

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

The description clearly states the verb 'returns' and the specific resources: top tools, top packs, and total call volume. It distinguishes itself from siblings by focusing on trending usage, not querying or searching.

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 (discovery, confirmation, alignment check), providing good context. However, it does not explicitly state when not to use the tool or contrast it directly with alternatives like ask_pipeworx or discover_tools.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds rich behavioral context: it requires exactly one parameter, explains monotonicity checks, partition-sum validation, semantic anchor (Jaccard similarity threshold), partition filter (placeholder slugs), and fill check against CLOB depth. This is far beyond what annotations provide.

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

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

The description is front-loaded with the key requirement ('REQUIRES one of...'), then explains each mode clearly. It uses structured sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize technical details. While somewhat verbose, every sentence adds necessary information for proper use.

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

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

The tool has no output schema, but the description fully explains the return structure: opportunities array with fields like gap_pp, suggested_trade, reasoning, and for event mode, partition_check with sum_yes_prices, gap_from_1, etc. It also covers edge cases (placeholders filter, fill check) and references a related tool for custom sizing. All critical behaviors are documented.

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

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

Schema description coverage is 100% with both parameters having clear descriptions. The tool description adds value by explaining the mode distinction, providing examples (e.g., 'fed-decision-may-2026'), and noting that full URLs are accepted. While the schema already defines the parameters well, the description enriches understanding of their practical use.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event and topic) with specific use cases, and contrasts with sibling tools like polymarket_edges or polymarket_fill_risk. The verb 'find' and specific noun phrases make the purpose highly specific.

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

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

The description explicitly recommends event mode for a specific market and topic mode for cross-event scanning. It warns that 'call with no args fails' and provides examples for each parameter. It also references polymarket_fill_risk for custom sizing, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral details: caching (1h KV cache), response structure (by_segment, diagnostics), data sources (FRED, GDELT), and caveats (Fed bets unreliable). 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 very long and dense, containing detailed technical explanations (e.g., specific alpha values for sports). It is front-loaded with the core purpose, but many details could be trimmed or moved to supplementary docs. Every sentence does not earn its place for basic selection and invocation.

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 having no output schema, the description thoroughly explains the response structure: top-level by_segment segments, fed_candidates/fed_note, and _diagnostics. It also covers all 9 parameters with clear defaults and use cases. An agent can fully understand inputs and outputs without additional 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?

Schema coverage is 100%, so baseline is 3. The description adds significant meaning beyond the schema, such as explaining tradeable-edge knobs (min_liquidity, max_spread_pp) and the special behavior of min_partition_leg_kelly. These details help an agent select and set parameters effectively.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the resource (Polymarket markets) and the action (scan and return opportunities). The detailed explanation of segments and knobs further clarifies, and while it doesn't explicitly differentiate from siblings, the rich context makes the purpose unambiguous.

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

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

The description explicitly says 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets,' providing clear context. It also explains when to use knobs like min_liquidity and max_spread_pp. However, it does not explicitly state when to use alternatives like polymarket_arbitrage or polymarket_edge_tracker, missing explicit exclusion guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds critical behavioral context: history limited by 60-day TTL, decay from daily closes (not intraday), and snapshot gaps due to cache misses. 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?

Well-structured with clear sections for purpose, args, response, and limits. However, the explanation of response fields is somewhat verbose; a more concise rendering would improve brevity.

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

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

Despite no output schema, the description fully explains the return structure (tracked, expired, snapshot_dates) and their meanings. It also covers limits and parameter semantics, making the tool self-contained.

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

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

Input schema covers both parameters with descriptions, so baseline is 3. The description adds default values (days=14, window='1wk') and clarifies 'snapshot family', enhancing understanding beyond schema.

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

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

Clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering a specific question about edge longevity. Distinguishes itself from sibling tools like 'polymarket_edges' by focusing on time-series behavior.

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

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

The description explains the tool's purpose but does not explicitly state when to use it over alternatives or when not to use it. The agent can infer usage from the purpose, but lacks direct guidance 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 indicate read-only, idempotent, non-destructive. The description adds rich behavioral context: how it walks the order book ladder, returns specific fields like top_of_book, slippage, and warns about forced directional risk and thin legs. No contradictions.

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

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

The description is well-structured with clear sections for single-market and basket modes, bold for emphasis, and bullet-like listing of return fields. Every sentence provides essential information. It is appropriately detailed for a complex tool.

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

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

With no output schema, the description fully enumerates return fields for both modes, including verdict, capture_ratio, profit_usd, thin_legs, and forced_directional_risk. It also explains the broader context of use in arbitrage strategies, making the tool's behavior completely understandable.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: explains side behavior in both modes, how size_usd is interpreted (spend vs proceeds vs settlement notional), and defaults and limits. It also explains what each return field means in context.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes between single-market and basket modes, and is differentiated from siblings like 'polymarket_arbitrage' and 'polymarket_edges' by explicitly being a prerequisite check.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround not capturable on thin books, partial fills cause directional risk) and that exactly one of 'market' or 'event' is required.

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

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

The description extensively covers behavioral traits beyond annotations: two modes, response structure, compatibility_warning conditions (non-equivalent bet shapes and unrelated events), temporal alignment, and skipped counters. It confirms read-only, idempotent behavior and adds critical context about when outputs are valid.

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

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

The description is lengthy but well-structured and front-loaded with the core purpose. Every sentence serves a purpose (modes, response, safety, temporal info). While it could be trimmed slightly, the detail is justified given tool complexity.

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

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

The description provides comprehensive context: purpose, modes, response contents, compatibility warnings, temporal alignment, and caveats about pre-mapped topics. Without an output schema, this level of detail ensures an agent understands what to expect and when the output is actionable.

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

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

All three parameters are described in the schema (100% coverage). The description adds value by explaining the two operating modes, the list of topic shortcuts, and how explicit parameters override the topic mapping. This goes beyond the schema descriptions.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage (intra-venue) and polymarket_edges by focusing on a specific cross-venue 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?

The description explains two modes (topic shortcuts and explicit tickers) and provides guidance on when spreads are meaningful via safety fields. However, it does not explicitly mention alternatives or when not to use this tool versus others like polymarket_arbitrage, reducing clarity for an AI agent selecting among siblings.

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

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

Annotations already provide safety profile (readOnly, idempotent, openWorld, not destructive). Description adds that it returns attribute rows and geometry, and includes usage pattern for sampling. No contradictions. Could mention error handling but not critical.

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

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

Two concise sentences with no fluff. Purpose, parameters, output, and example are front-loaded. Every sentence earns its place.

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

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

Comprehensive for a query tool with 6 parameters and no output schema. Covers purpose, origin of URL, parameters, return type, and sampling example. No gaps given annotations provide safety.

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 for all 6 parameters. Description adds value by explaining SQL-like behavior, comma-separated out_fields, and providing a concrete example ('where="1=1" + out_fields="*"'). This goes beyond the schema descriptions.

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

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

Description clearly specifies the tool queries ArcGIS Feature/Map Service layers by URL from search_datasets. Verb 'Query' with resource 'ArcGIS Feature/Map Service layer' is specific. It distinguishes from sibling tools like search_datasets and layer_info by focusing on data retrieval.

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 ties usage to search_datasets ('from search_datasets'), giving clear context. It provides an example for sampling. However, it does not explicitly state when not to use this tool or compare with alternatives like layer_info, missing a chance to fully distinguish.

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. The description adds valuable context: retrieval from persistent storage, scoping to identifier, and the listing behavior when key omitted. 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?

Four sentences, front-loaded with the core action, each sentence adds distinct information (core retrieval, usage context, scoping, pairing). No fluff or redundancy.

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

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

Given the tool's simplicity (one optional param, no output schema, rich annotations), the description covers purpose, usage, scoping, and sibling relationships. It could optionally mention the return format or behavior for missing keys, but it is largely complete.

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

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

Schema coverage is 100% for the single optional parameter 'key', with a description already specifying 'Memory key to retrieve (omit to list all keys)'. The tool description essentially repeats this without adding new parameter-level details, so no extra value beyond schema.

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

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

The description clearly states the tool retrieves a value saved via remember, or lists all keys if the key argument is omitted. It provides concrete examples of use (ticker, address, notes) and explicitly distinguishes from siblings remember and forget.

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

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

The description gives explicit guidance: use to look up previously stored context without re-deriving, and pairs with remember to save and forget to delete. It also clarifies scoping to the agent's identifier. No exclusions needed; alternatives are named.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context: setting mark_read:true flags returned events as read, affecting future calls. It also states that polling works fine, and the same feed is available via GET endpoint. 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 concise at four sentences, each serving a distinct purpose: purpose, return fields, filtering options, and additional notes (polling, alternative endpoint). It is front-loaded with the core action and avoids unnecessary repetition.

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

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

Given no output schema, the description adequately explains return fields (source, citation_uri, raw payload). It covers all parameters, mentions polling suitability, and provides an alternative access method. For a read-only tool with annotations, this description is complete enough for effective agent use.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds meaning beyond the schema by providing example filter values (e.g., 'sec_8k'), clarifying that 'since' expects an ISO timestamp, and explaining the effect of mark_read and unread_only. This additional context aids correct 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 starts with a clear action verb 'Pull fired events' and specifies the resource 'subscription feed'. It distinguishes itself from siblings like 'list_subscriptions' by focusing on events rather than subscriptions themselves. The mention of specific fields (source, citation_uri, raw event payload) further clarifies the tool's output.

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 guidance on when to use the tool (to pull alerts) and offers context on filtering parameters (type, since) and the mark_read option. It also mentions an alternative access method (GET endpoint) for scripts and dashboards. However, it does not explicitly contrast with all sibling 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, idempotentHint, and no destructiveness. Description adds behavioral context: fans out to multiple sources, fallback on rate-limit, soft-fail for patents, and returns structured changes with citation URIs. No contradictions.

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

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

Description is fairly concise given the complexity, front-loaded with query examples. Every sentence adds necessary context, though multiple examples of relative shorthand could be slightly trimmed. 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, description fully explains return structure (changes grouped by source, total_changes, citation URIs), covers multiple data sources with fallback logic, addresses USPTO status, and provides usage context. No missing critical 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?

Schema provides full parameter descriptions (100% coverage). Description adds value with relative shorthand examples for 'since' ('7d', '30d', '3m', '1y'), recommends '30d' or '1m' for monitoring, explains 'value' accepts ticker or zero-padded CIK, and notes 'type' only supports 'company'.

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

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

Description uses specific verbs ('What's new with X', 'latest on Y') and clearly states it returns a change feed for a company via SEC, GDELT/GNews, and USPTO. Explicitly differentiates from sibling 'entity_profile' which returns static profile instead.

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

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

Provides explicit guidance: use entity_profile for static profile, describes fallback logic (GDELT→GNews, USPTO soft-fail), and gives suitable values for 'since' like '30d' or '1m' for monitoring.

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

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

Discloses behavior beyond annotations: key-value pair scoped by identifier, persistence for authenticated vs anonymous (24 hours). Does not contradict annotations (idempotentHint true).

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?

Efficiently conveys purpose, usage, and behavior in a few sentences without redundancy. Front-loaded with main action.

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

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

Complete for a simple key-value store tool: covers authentication behavior, persistence, pairing with siblings, and provides examples. No output schema needed.

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

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

Schema covers 100% of params with descriptions. Description adds example keys and value types, providing additional context beyond schema.

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

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

The description clearly states the tool saves data for later reuse, with specific verb 'Save' and resource 'data'. It differentiates from siblings recall and forget by mentioning pairing with 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?

Explicitly says when to use: 'when you discover something worth carrying forward' with examples (resolved ticker, target address, etc.) and notes pairing with recall and forget, plus scoping and persistence info.

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

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

Annotations already indicate idempotent, read-only, non-destructive. Description adds that each call cascades through several lookup endpoints internally, replacing 2-3 manual lookups. This provides 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 but packed with useful information. Starts with example queries, core purpose, then supported types. Every sentence adds value, though could be slightly more 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?

No output schema, but description fully explains return values for each type (ticker+CIK+company_name for company; RxCUI+ingredient+brand for drug) and mentions citation URIs. Covers purpose, usage, params, and output 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%, baseline 3. Description adds detailed explanation of what each type supports, including input formats like ticker, CIK, name for company and brand/generic for drug. Also mentions auto-disambiguation for company input.

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 resolves names to canonical identifiers, provides example queries, lists supported types and their outputs. It distinguishes itself as the first tool to use when needing an ID, which differentiates from sibling 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 says 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. Does not explicitly mention when not to use, but the context is strong.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint as expected. The description adds behavioral details: probes each entity, ranks by score, surfaces most/least recognized, and returns 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?

The description is three sentences, front-loaded with the core function, and every sentence adds value. No redundant or vague language.

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

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

Given 4 parameters and no output schema, the description explains what the tool does, how it works (probes via ai_visibility_check), and what it returns (ranked list with metrics). This is sufficient for an agent to understand its capabilities and 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%, so baseline is 3. The description adds value by explaining the 'entities' parameter: first entry is treated as the subject for narrative, rest as competitors. It also clarifies the 'models' and 'context' parameters beyond schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities, using specific verbs like 'probes' and 'ranks', and differentiates from siblings like ai_visibility_check by emphasizing side-by-side comparison and competitive 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 gives a clear use case ('competitive AI-marketing audits') and example ('does Claude know about us as well as our competitors?'), implying when to use it. It mentions the internal call to ai_visibility_check, hinting at alternatives, but does not explicitly exclude other tools.

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

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

Beyond annotations (readOnlyHint, etc.), description discloses partial failures and bundlephobia's first measurement delay (5-30s), and explains that sources_failed lists timeouts while rest still returns. 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?

One dense paragraph, slightly long but efficient. Front-loaded with purpose. Could benefit from bullet points for readability, but no wasted sentences.

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

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

Despite no output schema, description lists all return fields and behaviors (advisory count, bundle size, ESM support, etc.). Covers edge cases like partial failures and delay. Complete for a multi-source composite 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%, both parameters clearly described. Description adds minor value by noting scoped packages are accepted and that version defaults to latest. Baseline 3 is appropriate.

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

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

Description clearly states it's a composite check for npm packages, specifying the data sources (deps.dev, bundlephobia) and the question it answers ('should I add this npm package'). Distinguishes from siblings by focusing on npm ecosystem and specific tool name.

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

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

Explicitly states when to use: 'whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. Also notes ecosystem limitation (NPM only in v1) and points to alternative (deps.dev:version) for other ecosystems.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds that it returns specific fields (name, summary, record_count, owner/org, url) and suggests chaining to siblings. 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?

Single sentence covering scope, action, return information, and chaining hint. Extremely concise with no wasted words.

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

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

Given no output schema, the description compensates by listing return fields and integration guidance. Could mention pagination or default behavior for org_id, but schema covers limit and org_id. Completeness is adequate for agent decision-making.

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

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

Schema coverage is 100% with clear descriptions for limit, query, and org_id. The description's 'by keyword' echoes schema but adds no new semantics. Baseline 3 is appropriate.

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

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

The description clearly specifies the tool searches Kansas State GIS open geospatial datasets by keyword, with examples of dataset types. It distinguishes itself from siblings like query_layer and layer_info, which operate on a specific Feature Service URL returned by this tool.

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

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

Provides clear context: use by keyword to find datasets. Explicitly tells the agent to pass the returned URL to query_layer or layer_info, showing when to use siblings. Does not state when not to use, but the context is sufficient.

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

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

Adds behavioral details beyond annotations: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag, and character offsets for verification. No contradiction with annotations.

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

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

Four sentences covering purpose, use case, pairing, technical detail, and limitation. Each sentence adds value, though slightly dense. Front-loaded with the main action.

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

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

Despite no output schema, the description explains return values (passages with offsets and scores), covers edge cases (truncation), and gives technical details (embedding model, window size). Complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing natural-language examples for the query parameter and clarifying the text parameter's source (fetched record). Limit parameter is only in schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific examples like SEC 10-K, article, and long tool results. It distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded and using saved 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?

Explicitly says 'Use when the record is too big to cram into the prompt' and explains the benefit of saving context. Suggests pairing with ask_pipeworx_grounded, but does not explicitly list when not to use or alternative tools.

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

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

The description adds behavioral details beyond annotations: it discloses the return of a subscription ID, rate limits for SMS (10/day), webhook auto-disable after 10 failures, and verification requirements. Annotations state idempotentHint=true and readOnlyHint=false, and the description does not contradict 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 well-structured with clear front-loading of the core purpose, followed by type-specific details and delivery channel breakdowns. While somewhat lengthy, every sentence adds necessary context, and examples aid 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 3 parameters, nested objects, and no output schema, the description covers all aspects: type variants, required vs optional fields, return value, prerequisites, rate limits, and failure behavior. It is fully 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?

Schema coverage is 100%, but the description significantly enriches parameter meaning with concrete examples (e.g., sec_8k items codes, polymarket_edge topics, fred_series series_id) and detailed delivery channel behavior (webhook signing, SMS verification, email validation). This adds value beyond the schema alone.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It specifies the verb 'Create' and the resource 'subscription to live-data event streams', distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides explicit usage context: when to create a subscription for monitoring live data events, with prerequisites (Pipeworx OAuth account) and exclusions (anonymous + BYO cannot persist). It also describes available types and delivery channels, though it does not explicitly state when not to use this tool.

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

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

Annotations already declare non-destructive, read-only, idempotent, and open-world hints. Description adds context about being an onboarding entry point and returning category-bucketed examples, 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?

Description is well-organized and front-loaded with key purposes and examples. While slightly long, every sentence contributes value. Minor room for abbreviation.

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 one optional parameter with full schema coverage, no output schema, and rich annotations, the description fully covers usage, argument semantics, and differentiation from siblings. Complete for this tool.

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

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

Schema coverage is 100%. Description explains the optional topic parameter with possible values (e.g., 'finance', 'pharma') and clarifies that omitting it gives a cross-category spread, adding meaning beyond the schema.

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

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

Clearly states it returns category-bucketed example questions and serves as the onboarding entry point. Distinguishes from siblings like ask_pipeworx by being a meta-tool for learning what to ask.

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 recommends using this tool first when unfamiliar with Pipeworx or to learn how to call meta-tools. Also explains when to pass the topic argument to focus on a specific area.

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

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

The description adds significant behavioral context beyond annotations: it clarifies that the row is deactivated (not deleted) and historical events remain, which addresses potential agent concerns about data loss. 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 concise, consisting of three short sentences that convey all necessary information without redundancy or fluff.

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

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

For a simple tool with one parameter and no output schema, the description provides complete context: what it does, ownership rules, and the effect on data. No gaps.

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

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

The schema has 100% coverage for the single parameter 'id', with a description that matches the tool's usage. The description does not add additional semantics, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id'), identifies the resource (subscription), and distinguishes 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?

It specifies ownership enforcement and the effect on historical data, providing context for when to use the tool. It doesn't explicitly list alternatives, but the context is clear given the sibling tools.

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

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

Description adds significant context beyond annotations: it specifies the return format (verdict, structured form, actual value with citation, percent delta), the domain (company-financial claims for US public companies via SEC EDGAR + XBRL), and the behavior of replacing sequential calls. No contradiction with annotations.

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

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

Description is well-structured with examples at the start, then usage guidance, scope, and return info. It is slightly verbose but efficient, with every sentence serving a purpose.

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

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

For a single-parameter tool with no output schema, the description covers purpose, usage, scope, and return format. It could be more explicit about the exact meaning of each verdict type, but overall it is sufficiently 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 covers 100% of the single 'claim' parameter with its own description. The tool description provides example formats but does not add substantial new meaning beyond what the schema already says ('Natural-language factual claim'). 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 identifies the tool as a natural-language claim verifier with specific examples ('Is it true that...', 'fact check') and states it handles company-financial claims. It distinguishes itself from siblings by specifying the domain and replacing multiple sequential calls.

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

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

Explicitly states when to use: when checking factual correctness of something a user said. It provides context on what it replaces, but does not explicitly state when not to use or list alternative tools.

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