Arcgis Sacramento

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which are consistent. The description adds value by detailing the return format per model (score, confidence, signals, raw_response) and cost implications (free vs BYO key).

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 purpose, and every sentence provides essential information without redundancy. No fluff.

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

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

Despite no output schema, the description thoroughly explains the return format and parameter details. For a tool of this complexity (probing multiple models, scoring), the description is 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% with descriptions for all parameters. The description adds useful context: default model, optional Anthropic key, and that 'context' helps disambiguate. This enhances understanding beyond the schema.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100). It specifies the default model and optional Anthropic with BYO key, distinguishing itself from siblings like scan_competitor_ai_presence.

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

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

The description provides context for when to use the tool (AI-marketing audits, pre-launch brand checks, competitive monitoring) and mentions the free default model versus the cost-bearing Anthropic option. It does not explicitly state when not to use it, but the guidance is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=true. Description adds that it routes to 4,552 tools across 1,160 sources and returns structured answers with stable citation URIs, providing useful context beyond annotations.

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

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

Description is somewhat verbose but well-structured: front-loaded with key preference statement, then domain list, then explicit usage rules, examples, and alternatives. Every sentence adds value, though could be tightened.

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 complex routing, description explains return value (structured answer with citations) and internal mechanism. It lacks error handling details but covers enough context for an agent to use it effectively.

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

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

Schema description coverage is 100% (6 parameters all documented as aliases for 'question'). The description's examples and mention of natural language input add marginal value but do not significantly extend schema information. 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 it is preferred over web search for a wide range of factual questions, naming specific domains like SEC filings, FDA drugs, economic stats, etc. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each.

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

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

Explicitly states 'START HERE for most questions', provides examples, and tells when to step up to alternative tools (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad multi-part questions). Also clarifies that breaking-news is handled internally.

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 cover readOnly, openWorld, idempotent, and non-destructive. Description adds detailed behavior (data extraction only from tool result, refusal reasons, return format) without contradiction. Rich 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?

Front-loaded with core purpose, well-structured with process and return format explained. Slightly verbose but every sentence adds value; could be trimmed marginally.

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 details return structure (answer, evidence, confidence, etc.) and refusal reasons. Covers usage context, trade-offs, and behavior comprehensively for a complex tool.

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

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

Schema description coverage is 100% with all parameter aliases documented. Description adds no extra meaning beyond schema, so baseline 3 is appropriate.

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

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

Clearly states the tool is a 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes itself from sibling 'ask_pipeworx' by being grounded and refusing to invent facts. Specific verb+resource with differentiation.

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 answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), along with a cost trade-off. Provides clear context and alternatives.

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by detailing specific behaviors: short-circuit on low-confidence matches, suppression of analysis fields on phantom matches, blocking mechanisms for closed markets, wide-spread tradeability notes, and resolution-rule risk with cancellation parsing. It also describes response shapes and fallback handling in news fields. No contradictions with annotations; the description adds extensive 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 long but highly informative, with structured sections using capital headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES). Every sentence earns its place by adding essential detail. Could be slightly more concise, but the density of utility justifies the length. Front-loads core function and usage phrases.

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 comprehensively explains the response structure (market analysis, evidence, resolver contract, parent_event, news error fields, safety mechanisms). It covers error states (low-confidence, closed market, wide spread, cancellation risk) and edge cases. For a complex tool with 3 parameters, this is fully complete for an agent to understand inputs, outputs, and behavior.

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 meaning by explaining the market parameter's accepted formats (slug, URL, question text) and providing examples. It elaborates on the depth enum (quick vs thorough) with practical advice, and the include_raw parameter with a clear recommendation and use cases. While the schema already describes parameters, the description provides valuable context that aids correct invocation.

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 Pipeworx data in one call. It specifies input types (slug, URL, question text) and the output (evidence packet + market-vs-model comparison). The usage statements ('Use for should I bet on X') provide immediate clarity, and the detailed classifier list and fan-out examples distinguish this from generic research tools. Despite not explicitly differentiating from siblings, the domain specificity (Polymarket bets with data packs) makes its purpose unmistakable.

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

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

The description includes clear usage prompts ('Use for...') but does not explicitly state when NOT to use this tool or mention alternatives among siblings. An agent could infer from the sibling list that tools like polymarket_edges or polymarket_arbitrage are for different purposes, but the description lacks direct guidance. This is a moderate gap for an otherwise detailed definition.

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 significant context: data sources (SEC EDGAR/XBRL, FAERS), fiscal year handling, sorting by primary metric, and citation URIs. No contradictions.

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

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

The description is a single dense paragraph but front-loads usage examples and effectively conveys all necessary information. It is efficient with minimal 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 complex tool comparing multiple entities across two types, the description covers data sources, metric details, sorting behavior, and output format (paired data + citation URIs). It is highly complete without 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?

Schema coverage is 100% with basic descriptions. The description adds detailed meaning: explains what data is pulled for each type (e.g., 10-K metrics for companies, adverse-event counts for drugs) and that results are sorted. This goes beyond the schema.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It uses specific verbs like 'compare', 'rank', 'head to head' and explicitly distinguishes from sequential single-pack lookups, making purpose and sibling differentiation clear.

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

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

The description provides explicit usage examples (e.g., 'Compare X and Y', 'X vs Y') and strongly advises preferring this tool over sequential lookups. It could be more explicit about when not to use it, but the context is sufficiently clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds account requirement, time expectation (15-60s), parallel tool routing (4,552 tools), return format (findings packet with evidence, confidence, source, gaps[]), and that it never invents. 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?

Front-loaded with critical usage info (account requirement, alternatives). Every sentence is informative and necessary. No redundancy despite length.

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 complexity (massive parallel research, no output schema), description covers: what, how (decomposition, routing), return format, limitations, alternatives, account requirements, time expectation. Leaves no gaps for an agent to misinterpret.

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

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

Schema covers both parameters with descriptions. Description adds meaning: depth's enum values correspond to number of facets (quick=3, standard=5, thorough=8), and question is natural language. Adds value beyond schema, but baseline 3 already high due to 100% schema coverage.

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

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

Clearly states it does grounded multi-source research across 1160 structured data sources, decomposes questions into facets, routes to tools in parallel, and returns a findings packet. Explicitly distinguishes from siblings ask_pipeworx and ask_pipeworx_grounded by scope and data sources.

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

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

Explicitly says 'Best for broad/multi-part questions over structured data' and provides when-not-to-use: single lookups use ask_pipeworx, breaking news use ask_pipeworx. Also mentions account requirement and that depth:'thorough' needs a paid plan, with an alternative for non-signed-in users.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds value by clarifying that returned tools are 'ready to call directly, no second schema lookup needed' and that results include curated examples. This goes beyond the annotations without contradicting them.

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

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

The description is relatively long but front-loaded with the core purpose and usage guidance. Every sentence adds value (purpose, domain examples, output details, usage advice). Could be slightly tighter, but remains efficient for the information provided.

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

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

Given the tool's role as a discovery interface among 33 siblings, the description is complete: it explains when to call it, what it returns (names, descriptions, full schemas with examples), and how to use it. No output schema is present, but the description sufficiently implies the return format.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters. The description adds no new semantic detail per parameter but does mention that query accepts multiple aliases (task, q, description, search), which is useful. This is adequate but not outstanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many example domains (SEC filings, FDA drugs, etc.) and explains the output (top-N tools with schemas). This highly distinguishes it from sibling tools that are task-specific.

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

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

The description explicitly advises to call this tool 'FIRST when you have many tools available and want to see the option set.' This provides clear when-to-use guidance. It lacks an explicit when-not-to-use statement, but the context strongly implies it's not needed when the target tool is already known.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses data sources (SEC EDGAR, XBRL, USPTO, GDELT, GLEIF), return details (e.g., sorted fundamentals, up to 5 filings with URIs), and known limitations (USPTO soft-fail). 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 dense but front-loaded with example queries and a clear purpose statement. Slightly long due to enumerated outputs, but 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 exists, yet the description thoroughly explains return fields, sorting, fallbacks, and limitations. For a tool with only 2 required parameters, this provides complete contextual guidance.

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 practical examples (ticker vs. zero-padded CIK) and clarifies that names are not supported. This goes beyond the schema's brief descriptions.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call'. It lists specific outputs (CIK, filings, fundamentals, patents, news, LEI) and distinguishes from chaining multiple 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?

Provides explicit usage triggers ('Tell me about X', 'research Acme', etc.) and states when to prefer this tool over alternatives. Also clarifies that names are not supported, advising to use resolve_entity first.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds context about the nature of the operation (deleting stored memories) and appropriate use cases (clearing sensitive data). It does not contradict 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 with no wasted words. Each sentence serves a purpose: stating the action, providing usage scenarios, and suggesting complementary tools. It is front-loaded with the core verb.

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

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

Given the simple input schema (one required parameter), the presence of annotations that cover safety profile, and the absence of an output schema, the description is complete. It explains what the tool does, when to use it, and how it relates to sibling tools.

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

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

Schema coverage is 100% and the schema provides a description for the 'key' parameter. The tool description does not add additional meaning beyond what the schema already states (e.g., 'Memory key to delete'), so 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 the specific verb 'Delete' and explicitly identifies the resource as a 'previously stored memory by key'. It distinguishes itself from the sibling tools 'remember' (store) and 'recall' (retrieve), 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 provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. It also advises pairing with 'remember' and 'recall', implicitly guiding 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 (readOnlyHint, idempotentHint, openWorldHint, non-destructive) already convey safety, and the description adds important behavioral details: it fetches the page, extracts title/description/key links, outputs standard markdown, and is ready to drop at site-root. 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 highly concise: a single sentence for purpose, then a brief explanation of the process and output, followed by a short bullet list of use cases. Every sentence adds value with no filler.

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

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

For a tool with 2 parameters, no output schema, and no nested objects, the description covers the core functionality, output format, and practical use cases adequately. Combined with rich annotations, the agent has sufficient information to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (url with example, max_links with default and max). The description repeats this information without adding new semantic meaning beyond what the schema provides, resulting in a baseline score of 3.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt), and target AI crawlers. It distinguishes from sibling tools by focusing specifically on llms.txt generation, which none of the siblings do.

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

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

The description provides explicit use cases (indexing client sites, drafting for own project, auditing competitors) but does not explicitly state when not to use or contrast with alternatives. The context is clear but lacks exclusions.

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

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

Annotations clearly mark this as readOnly, idempotent, and non-destructive. The description adds behavioral context by detailing the types of information retrieved (fields, geometry, count, capabilities), which is beyond the annotations. No contradictions.

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

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

Single sentence captures the essence: verb, resource, and output details. 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?

The description fully explains the tool's output schema (fields, geometry type, count, capabilities) despite no formal output schema. It's complete for the tool's purpose, but could hint at URL validation (e.g., must end in '/{id}').

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 schema already documents the 'url' parameter sufficiently. The description only briefly mentions 'by url', which is already present. No additional parameter-specific semantics are provided.

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 'Get' with clear resource 'ArcGIS Feature/Map Service layer's schema'. It lists the exact information returned (fields, geometry type, count, capabilities) and explicitly ties it to a URL input, distinguishing it from querying or searching tools in the sibling list.

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 no explicit guidance on when to use this tool versus its siblings like 'query_layer' or 'search_within'. It only implies its use case through the content described. It lacks 'when-to-use' or 'when-not-to-use' statements, so it's adequate but not exceptional.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds specific return fields and confirms it lists the caller's subscriptions, which is consistent and provides extra clarity beyond annotations.

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

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

The description is two sentences, front-loading the primary action and output, then providing usage guidance. No extraneous information.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description sufficiently explains what it does, what it returns, and when to use it.

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

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

The input schema covers the single parameter 'include_inactive' with full documentation. The description does not re-iterate parameter details, which is acceptable given 100% schema coverage.

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

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

The description clearly states the tool lists active subscriptions for the caller, specifying the returned fields (id, type, etc.). This distinguishes it from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description advises using the tool to review current subscriptions before adding more or to find an ID to cancel. This provides clear usage context, though it could also mention when not to use it.

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

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

The description adds important behavioral details beyond annotations: 'Rate-limited to 5 per identifier per day. Free; doesn't count against your tool-call quota.' It also mentions that signals affect the roadmap. Annotations are all false (not readOnly, not idempotent, etc.), 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 concise—5 sentences packed with actionable information. It front-loads the purpose, then usage guidelines, then behavioral notes. No redundant or filler text.

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 (3 parameters, no output schema), the description covers input semantics, when to use, rate limits, and quota impact. It is complete enough 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%, so baseline is 3. The description adds value by specifying message length ('1-2 sentences typical, 2000 chars max') and reiterating the meaning of the type field with context, though the schema already provides enum descriptions. The nested object 'context' is not elaborated in the description, but the schema covers it.

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 purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses specific verbs and identifies the resource (Pipeworx team). It distinguishes from sibling tools by focusing on feedback rather than queries, research, or other actions.

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

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

The description explicitly states when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear negative guideline: 'don't paste the end-user's prompt.' This helps the agent select this tool 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?

Adds value beyond annotations by stating data source ('CF analytics-engine'), no PII, caching behavior (5min-1h), and parameter window semantics. Annotations already indicate safety; description enriches behavioral understanding.

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 paragraph, front-loaded with main purpose, then use cases and data source. Every sentence earns its place; no redundancy.

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

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

Given simple tool (1 param, no output schema), description covers return value, use cases, data source, caching, and parameter semantics. Fully complete for the complexity.

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

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

Schema coverage is 100% with enum and description. Description adds default and interpretation ('shorter windows surface what's hot right now; longer windows show steady-state demand'), providing extra meaning.

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

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

Description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window' with use cases, providing specific verb+resource and distinguishing from siblings like ask_pipeworx or discover_tools.

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

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

Explicitly lists three useful scenarios (hot data sources, confirming canonical tool, alignment check). Lacks explicit when-not-to-use or alternatives, but use cases are clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds rich behavioral details: scanning scope, thresholds (3pp, 0.30 Jaccard, 20% placeholder), fill check with realizable vs theoretical edge, and placeholders filter. No contradiction; fully describes operational behavior.

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

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

The description is well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with core purpose. However, it is fairly long and contains some details that could be inferred or moved to a separate help section. Still, every sentence adds value.

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

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

Despite lacking an output schema, the description fully explains return values (opportunities[] with fields, partition_check object, fill check details). It also covers edge cases (placeholder filtering, similarity threshold, fill check conditions). For a complex tool with no output schema, this is exceptionally complete.

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

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

Schema coverage is 100%, but description adds significant meaning beyond schema: explains the 'event' parameter expects a Polymarket event slug with examples, 'topic' expects a seed question with examples, and describes the behavior when no arguments are passed. Also details the differences between event and topic modes.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies three distinct modes (no args, event, topic) with specific behaviors, making the purpose highly specific and distinguishable from siblings.

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

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

Explicitly tells when to use each mode: 'Call with NO args for a trending_scan', 'pass event for...', 'topic for...'. Recommends 'event (recommended for a specific market)'. Provides context like SEMANTIC ANCHOR, PARTITION FILTER, and FILL CHECK, guiding when to avoid trades. Although not explicitly comparing to siblings, the detailed usage instructions compensate.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds extensive behavioral context: model families, edge calculations, response structure, diagnostics for empty segments, caching at 1h KV level, and exclusion of Fed candidates due to unreliable signal. 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 long but well-structured with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.) and front-loaded purpose. Each sentence adds specific technical detail, making it appropriately sized for the complexity, though slightly dense.

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 details full response structure (by_segment, fed_candidates, diagnostics) and explains why segments may be empty. Covers edge fields, knobs, and caching. Missing error cases but diagnostics handle edge cases well.

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

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

All 9 parameters have schema descriptions (100% coverage), so baseline is 3. The description adds value by explaining tradeable-edge knobs, why min_kelly doesn't filter partition arbs, and providing usage context for parameters like min_partition_leg_kelly and slippage_pp, going beyond the schema.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It identifies the specific resource (Polymarket markets) and the action (find edges), and distinguishes itself from siblings by focusing on model-driven opportunities without paging.

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 is built for 'what should I bet on today' and explains when to use it, including tradeable-edge knobs like min_liquidity and max_spread_pp. However, it does not explicitly compare to siblings like polymarket_arbitrage or state when not to use it, missing some 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 declare the tool as read-only and idempotent. The description adds valuable behavioral context: it uses daily snapshots, has a 60-day TTL, decay computed from daily closes (not intraday), and response structure details. This extra transparency is helpful.

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, front-loading the core purpose. Each sentence adds value, though some technical detail could be streamlined. It is not overly verbose for the complexity.

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

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

Given the complexity (time-series analysis) and no output schema, the description fully explains response fields (tracked, expired, snapshot_dates) and limitations (60-day TTL, snapshot start). It covers all necessary context for an agent to use the tool correctly.

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

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

Input schema has 100% coverage for both parameters with descriptions. The description adds meaning by explaining 'window' as snapshot family and default '1wk', and 'days' with default/max values. It does not simply repeat schema but enriches understanding.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry'. It uses specific verb 'answers' and identifies the resource (Polymarket edges over time). It distinguishes from siblings like 'polymarket_edges' by focusing on time-series and decay analysis.

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

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

The description implies usage for assessing edge persistence but does not explicitly state when to use this tool versus alternatives like 'polymarket_edges' or 'bet_research'. No explicit 'when to use' or 'when not to use' guidance is provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description correctly does not contradict them. Beyond annotations, the description adds behavioral context: it warns about thin books ('theoretical overround on thin books is not capturable'), explains that partial basket fills convert arbs into directional positions, and describes the verdict (clean|degraded|cannot_fill). This is adequate but could mention rate limits or error conditions.

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 and well-structured with explicit headings for single-market and basket modes, bold for emphasis on key requirements and warnings. At ~200 words, it is slightly verbose but every sentence contributes meaning. No wasted words, but could be tightened by removing some redundancy in the basket section.

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

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

Given the tool has two modes, four parameters, no output schema, and no nested objects, the description provides a comprehensive overview of return values (e.g., top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket). It could mention error states or rate limits, but the level of detail is impressive for a description.

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

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

Schema coverage is 100% with all four parameters described. The description adds value beyond the schema by explaining the default behavior for side in basket mode ('default auto — sell if partition sum > 1, buy if < 1'), clarifying size_usd interpretation in single-market vs basket mode, and detailing return fields. This surpasses the baseline of 3 for full schema coverage.

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

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

The description clearly identifies the tool as a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes single-market and basket modes with specific verbs (walks the ladder, returns top_of_book, etc.), and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use it (before acting on arb signals or trades above $500).

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' The description also warns against partial basket fills converting arbs into unhedged directional positions, which is the dominant loss mode. The tool requires one of market or event parameters, clearly indicating when to use each mode.

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 openWorldHint. The description adds extensive behavioral context: compatibility_warning conditions, temporal alignment, skipped_cross_type/subtype counters, and that pre-mapped topics are often non-tradeable. This exceeds 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 well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and uses clear formatting. It is somewhat verbose but each sentence adds value. Minor conciseness loss from repetitive phrases like 'pre-mapped ≠ tradeable'.

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

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

No output schema exists, so the description must cover return structure. It does so thoroughly: leg-by-leg prices, matched spreads, safety fields. Given the complexity of cross-venue logic and three optional params, the description provides nearly everything an agent needs.

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 beyond it: explains the topic enum list, gives example values (e.g., 'KXFED-26OCT'), and clarifies that explicit parameters override topic. This adds significant meaning.

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

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

The description clearly states the tool computes cross-venue spread between Polymarket and Kalshi for the same question, distinguishing it from sibling tools like polymarket_arbitrage (intra-venue). It specifies two modes (topic shortcuts and explicit IDs) and what the response includes.

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 with examples and warns that most pre-mapped topics currently return compatibility_warning. It provides guidance on when to use each mode but does not explicitly contrast with siblings like polymarket_arbitrage, though the purpose implies cross-venue is unique.

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, indicating a safe, read-only operation. The description adds behavioral context by noting it returns 'attribute rows (and geometry)' and describing SQL-like query capabilities, pagination, and field selection, which goes 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 concise (2-3 sentences) and front-loaded with the core purpose. Every sentence provides useful information: the resource type, origin, SQL-like parameters, and a sampling tip. 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 has 6 parameters with 100% schema coverage, annotations for safety, and no output schema, the description is mostly complete. It explains query parameters and basic return shape, but lacks explicit detail on the response structure (e.g., array of objects vs. GeoJSON). This is a minor gap for a query tool.

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

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

Schema coverage is 100%, but the description adds significant value by explaining the SQL-like nature of where, comma-separated out_fields, order_by format, limit with max 2000, and offset usage. It also gives practical examples like where='1=1' and out_fields='*', enhancing understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Query an ArcGIS Feature Service / Map Service layer by its url (from search_datasets).' It includes a specific verb ('query'), a resource type ('ArcGIS Feature Service / Map Service layer'), and indicates its origin from search_datasets, which helps differentiate it from sibling tools that might fetch metadata or perform other operations.

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

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

The description implies usage after obtaining a URL via search_datasets and provides practical tips like using where='1=1' for sampling. However, it does not explicitly state when not to use this tool, nor does it compare with alternatives like layer_info for metadata retrieval, leaving some ambiguity about selection criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about scoping (by identifier) and the dual behavior (retrieve vs list). It also explains the pairing with remember and forget. 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 three concise sentences, each adding value: purpose, use case, scoping, and pairing. No wasted words, front-loaded with the core 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?

Given the tool's simplicity (1 parameter, no output schema, clear annotations), the description covers all necessary aspects: what it does, how to use it, when to use it, and how it fits with related tools.

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

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

Schema coverage is 100% with one parameter 'key' described as 'Memory key to retrieve (omit to list all keys)'. The description reinforces this but does not add additional semantics beyond explaining the omit behavior. 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 clearly states the verb ('Retrieve' or 'list') and the resource ('a value previously saved via remember' or 'all saved keys'). It distinguishes itself from sibling tools like 'remember' and 'forget' by explicitly naming them and explaining the relationship.

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 look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions scoping to user identifier. However, it does not explicitly state when not to use it or provide alternative tools beyond the implied pairing.

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, openWorld), the description discloses that alerts can be marked as read via mark_read, which advances cursor state. This is a behavioral trait not captured by annotations. However, there is a potential contradiction: mark_read modifies state while readOnlyHint is 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?

The description is a single paragraph with no wasted words. It front-loads the purpose and efficiently covers return format, filtering, mark_read, polling, and alternative access. Every sentence contributes necessary information.

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

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

For a tool with 5 optional parameters and no output schema, the description explains the return structure (source, citation_uri, payload), filtering options, mark_read behavior, and polling suitability. It does not mention the unread_only parameter but otherwise is comprehensive.

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

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

Schema coverage is 100% (baseline 3). The description adds value by explaining type filter with an example ('sec_8k'), specifying since as ISO timestamp, clarifying mark_read effect, and stating limit default. It omits unread_only, but overall enhances 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?

The description starts with 'Pull fired events from your subscription feed,' clearly stating the verb and resource. It details what data is returned (source, citation_uri, raw payload) and mentions filtering, making the purpose distinct from siblings like subscribe or 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?

The description indicates when to use the tool (to retrieve recent alerts) and notes that polling works fine, implying suitability for repeated queries. It also mentions an alternative HTTP endpoint, but does not explicitly exclude contexts or compare with 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?

The description discloses significant behavioral traits beyond the annotations: fanning out to multiple sources, fallback logic (GDELT→GNews on rate-limits/5xx), USPTO soft-failure, return structure (changes grouped by source, total_changes, citation URIs). All annotations (readOnlyHint, openWorldHint, etc.) are consistent and not contradicted.

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

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

The description is well-structured: starts with memorable example queries, then explains functionality, fallback behavior, parameter details, and ends with sibling differentiation. Every sentence is informative; no filler. Appropriate length 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?

Despite having no output schema, the description clearly explains what the tool returns (structured changes grouped by source, total_changes count, pipeworx:// citation URIs). It covers all aspects needed for an agent to decide and invoke correctly, including source-specific behavior and error handling.

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

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

Schema coverage is 100% with basic descriptions. The description adds substantial value: explains the `since` parameter accepts ISO dates and relative shorthand ('7d', '30d', '3m', '1y'), suggests default ('30d' or '1m'), and clarifies `value` can be ticker or zero-padded CIK. This exceeds baseline expectations.

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

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

The description uses specific verbs like 'change feed', 'fans out to SEC EDGAR, GDELT→GNews fallback, USPTO' and provides concrete example queries ('What's new with X', 'latest on Y'). It also distinguishes from the sibling tool 'entity_profile', making the purpose clear and unambiguous.

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

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

Explicit guidance is given: 'Use entity_profile instead when you want the static profile' clearly states when not to use this tool. The examples ('What's new with X', 'latest on Y') imply appropriate usage contexts. No ambiguity.

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

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

Annotations indicate mutating (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description adds valuable context: persistence scoped by user identifier, with 24-hour retention for anonymous sessions, which is not in annotations.

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

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

Three sentences with no wasted words. First sentence states the core purpose, followed by usage guidance and behavioral details. Efficient and well-structured.

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

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

For a simple key-value store, the description covers purpose, usage, persistence behavior, and pairing with other tools. No output schema exists, but return values are implied. Complete and 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?

Schema has 100% coverage for both parameters with good descriptions. The tool description reinforces the key-value nature and provides usage examples (e.g., 'resolved ticker'), adding contextual meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It differentiates from sibling tools recall and forget, which are explicitly mentioned as pairs.

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 ('when you discover something worth carrying forward') and mentions alternatives (recall to retrieve, forget to delete). Also explains scoping and persistence behavior.

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; description adds internal cascade and efficiency benefit. 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 examples first, then guidance, then type details. Slightly verbose but each sentence adds value.

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

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

Explains return values for each type despite lack of output schema. Missing explicit error handling, but adequate 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?

With 100% schema coverage, description enriches both parameters with examples, input formats, and return details beyond 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?

Description explicitly states it resolves a name to canonical ID, with specific examples like ticker, CIK, RxCUI. Clearly distinguishes from siblings by noting it replaces manual 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?

States 'Use FIRST whenever you have a name but need an ID.' Provides clear context for when to use, though doesn't 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 significant behavioral context beyond the annotations. It explains that the tool probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density per entity. It also notes the first entity is treated as the subject for narrative. No contradictions with annotations (readOnlyHint, idempotentHint, etc.).

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

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

The description is extremely concise: two sentences plus a brief use case example. Every phrase adds value—probing, ranking, output fields, use case. No redundant or vague language. It's front-loaded with the core action and then details.

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

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

Given the tool's moderate complexity (4 params, batch operation, dependency on ai_visibility_check), the description covers the goal, inputs, output format, and use case. The lack of an output schema is compensated by describing the returned fields. It might miss details on error behavior or rate limits, but for a wrapper tool, this is adequate.

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

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

Schema coverage is 100% with all parameters having descriptions. The description adds value by clarifying that entities should be 2-8 and the first is the subject, and that context disambiguates common names. It doesn't repeat schema details but ties them to the tool's batch behavior. Some nuance about models and _apiKey is implicitly covered.

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: comparing AI visibility across multiple entities side-by-side, probing each with ai_visibility_check, ranking, and returning results. It distinguishes from siblings like ai_visibility_check and compare_entities by explicitly mentioning the batch comparison and ranking. The use case example ('does Claude know about us as well as our competitors?') concretely illustrates the 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 a clear use case (competitive AI-marketing audits) and an example question, guiding when to use the tool. It implies usage when comparing multiple entities, but does not explicitly state when not to use it or directly differentiate from sibling tools like compare_entities. The context of being a batch version of ai_visibility_check is implied but not explicit.

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 partial failure behavior: bundlephobia first measurement takes 5-30s, sources_failed lists timeouts, rest returns. Annotations already indicate idempotent, read-only, not destructive; description adds practical behavior details.

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

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

Two sentences pack all essential information: purpose, sources, usage, scope, behavior, and return value list. 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?

Covers purpose, sources, return fields, scope, failure modes. No output schema but description enumerates summary block fields. Lacks detail on per-advisory structure and links, but sufficient for an agent to understand tool's output.

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

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

Schema coverage is 100% with descriptions for both parameters. Tool description adds no new semantic information beyond what schema already provides. Baseline 3 is appropriate.

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

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

Tool name and description clearly state it's a composite check for npm packages using deps.dev and bundlephobia. Distinguishes from sibling tools by being the only dependency scanning 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?

Explicitly says when to use: when agent asks about safety, popularity, size, or cost of adding a package. Also notes NPM-only scope and fallback for other ecosystems via deps.dev:version directly.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds return format (name, summary, record_count, url) but no additional behavioral traits beyond what annotations imply.

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, no fluff, front-loaded with purpose and actionable guidance.

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

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

No output schema, but description clearly lists return fields and how to use the URL. Adequate for a read-only search tool with full annotations.

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

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

Schema coverage is 100%, so description adds no new parameter meaning. The examples in the description echo the schema's examples, providing no extra semantic value.

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

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

Clear verb+resource+examples (GIS datasets by keyword). Distinguishes from siblings like query_layer by specifying what it returns and how to further use the URL.

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 (search datasets) and what to do with the returned URL (pass to query_layer/layer_info). Does not explicitly state when not to use or list alternatives among many siblings, but context is clear.

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

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

Annotations already show readOnlyHint, idempotentHint, etc. The description adds valuable behavioral context: uses BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation flag, and result structure (passages with offsets and scores). 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?

Single, well-structured paragraph that front-loads purpose, then usage guidance, then technical details. Every sentence adds value without redundancy. Efficient use of 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?

Despite no output schema, the description fully explains return values (passages with offsets and scores), truncation behavior, embedding details, and pairing with sibling tools. Covers all needed context for an AI agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra context beyond schema: explains that 'text' is the document to search (max 200K chars, matching schema), 'query' is natural-language with examples, and 'limit' is 1-20 with default 5. The overall paragraph clarifies how parameters affect results.

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

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

The description clearly states the tool performs 'Semantic search INSIDE a fetched record', specifying the verb 'search' and the resource (inside a text). It distinguishes from siblings like search_datasets by emphasizing it works on already-fetched content, and provides concrete examples (SEC 10-K, article).

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt — search_within saves context'. Mentions pairing with ask_pipeworx_grounded as a complementary tool. Lacks explicit 'when not to use', but the guidance is clear and actionable.

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

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

Annotations indicate write operation (readOnlyHint false, destructiveHint false). Description adds behavioral details: requires authentication, returns new subscription id, delivery limits, webhook HMAC signing and auto-disable. No annotation contradictions.

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

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

Description is detailed but well-structured, using inline formatting to separate sections. Every sentence adds value, though it could be slightly more organized into bullet points for readability. No filler content.

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

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

Given 3 parameters with nested objects and no output schema, the description is highly complete: covers all subscription types, parameter formats, delivery options with constraints, return value, and prerequisites. No gaps in context.

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

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

Schema coverage is 100%, but description enriches each parameter with type-specific formats (e.g., sec_8k params with ticker/items, delivery object with email/SMS/webhook behaviors) and constraints (phone verification, SMS cap). Provides actionable examples 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?

Clearly describes creating a proactive monitoring subscription to a live-data event stream and returning a subscription ID. Distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 (monitor specific events) and prerequisites (Pipeworx OAuth account; anonymous/BYO cannot persist). Provides examples for each supported type and delivery channel constraints (phone verification, 10/day cap, webhook auto-disable).

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds that it returns category-bucketed examples with tool shapes, which is useful beyond annotations. No contradiction.

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

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

Front-loaded with common trigger phrases. Though slightly verbose, every sentence adds value. Structured logically from purpose to usage to return details.

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

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

No output schema, but description fully explains return format (category-bucketed examples with tool calls) and provides complete guidance on usage, parameter, and when to invoke.

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

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

Schema has 100% coverage with a description for 'topic'. Description adds list of possible values and effect of omitting vs. providing. Significantly enriches 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?

Description clearly states it's an onboarding entry point that returns example questions with exact tool calls. It uses specific verbs 'ask' and 'get started' and differentiates from siblings like discover_tools and ask_pipeworx.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and describes calling with no arguments vs. topic. Does not explicitly list when not to use, but the context is clear.

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

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

The description adds significant context beyond annotations: it clarifies the action is a deactivation (not deletion), mentions ownership enforcement, and that historical events remain via recent_alerts. Annotations already indicate non-destructive and idempotent, so description complements well.

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 that are front-loaded with purpose and constraints. No unnecessary words; each sentence adds essential information.

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

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

For a simple tool with one parameter and no output schema, the description covers all essential aspects: action, constraint, side-effects, and relation to other tools (recent_alerts).

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 description adds value by stating the id comes from 'subscribe' and that it's a UUID. The schema already describes the parameter, but the description provides context about its origin.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 mentions ownership enforcement ('you can only cancel your own subscriptions'), which is a key usage condition. It does not explicitly state when not to use it, but the condition implies it's only for own subscriptions.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds significant behavioral context: it returns a verdict with specific types, extracted structured form, actual value with citation, and percent delta. It also discloses the data source (SEC EDGAR + XBRL) and version (v1). No contradictions with annotations.

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

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

The description is well-structured, starting with example utterances, then usage context, then technical details. Every sentence adds value, though it could be slightly more concise. It is front-loaded with the most important information.

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

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

Given no output schema, the description thoroughly explains the output (verdict types, structured form, citation). It covers domain, limitations, and use case. It could mention error handling or unsupported claims, but overall it is fairly complete for a single-parameter tool.

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

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

Schema coverage is 100% with a description for the single parameter 'claim'. The description adds extra guidance on what kind of natural-language claims are expected (e.g., 'Apple's FY2024 revenue was $400 billion') and explains the output, which is not required by the schema but adds value.

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

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

The description clearly states the tool verifies natural-language claims against authoritative sources. It provides specific verbs ('fact check', 'verify', 'confirm or refute') and identifies the resource (claims). It distinguishes from siblings by noting it replaces 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?

The description tells when to use ('whenever the agent needs to check whether something a user said is factually correct') and gives examples. It implies domain limitations (company-financial claims only) but does not explicitly name alternative tools for other claim types.

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