Arcgis Henderson

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive hints, so the bar for additional disclosure is lower. The description adds valuable behavioral context beyond annotations: the default model (Workers AI Llama-3.3-70b) is free, probing Anthropic requires a BYO key with direct billing, and the return shape includes per-model details plus a combined view. This is useful but not exhaustive (e.g., no mention of rate limits or error handling), hence a 4.

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 compact at three sentences, with the core purpose front-loaded. It covers purpose, default behavior, cost, expected output, and use cases without redundancy or filler. Every sentence adds value, making it highly concise and well-structured.

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

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

Given the tool has 4 parameters (1 required), no output schema, and no enums, the description is remarkably complete. It specifies what the tool returns (per-model {score, confidence, signals, raw_response} + combined view), explains the default model and optional Anthropic probing, and provides real-world use cases. It even mentions the return structure, which is essential since there is no output schema. This covers all critical aspects for an agent 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?

The input schema already has 100% coverage with descriptions for all four parameters, so the baseline is 3. The description adds meaningful semantics on top: it clarifies that 'workers-ai' is the default free model and that _apiKey is only needed for Anthropic, plus explains the cost implications. This extra context justifies a 4.

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

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

The description clearly states the tool's function with a specific verb ('Probe') and resource ('one or more LLMs'), and explains the output (visibility score 0-100 per model). It is clear enough to understand the tool's purpose, but it does not explicitly differentiate itself from related sibling tools like scan_competitor_ai_presence, so it falls short of a 5.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring') which gives clear context for when to use the tool. However, it does not mention when NOT to use it or name alternative tools, so it lacks exclusions or explicit alternatives that would earn a 5.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints. The description adds meaningful context: it routes to the right tool, fills arguments automatically, returns stable pipeworx:// citation URIs, works on every tier, and is a single fast call. This goes beyond the structured 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 front-loaded with critical guidance and every sentence provides value: alternatives, examples, escalation path, and operational details. It is dense but not wasteful, earning a 4 rather than a 5 due to its 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 the tool's complexity and the absence of an output schema, the description covers purpose, usage, alternatives, citations, and examples effectively. It does not discuss potential failure modes or return-format details, but those are not critical for an entry-point tool with rich 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%, and the description examples illustrate natural-language usage. The description does not add parameter-level meaning beyond the schema's alias explanation, which is already sufficient. Baseline 3 applies since the schema handles the details.

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: routing questions to one of 5,366 tools across verified sources and returning structured answers with citations. It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its specific role 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?

Explicitly says 'PREFER OVER WEB SEARCH' and lists exact use cases (SEC filings, FDA data, etc.), trigger phrases, and examples. It also provides escalation guidance to ask_pipeworx_grounded and deep_research, plus notes about breaking news, making when-to-use and when-not-to-use crystal 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 readOnly/idempotent, and description adds context about the experimental status, the active-candidate lifecycle, and that it is a full working router rather than a fallback. This enriches the safety profile without contradicting annotations.

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

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

The description is four sentences that each add critical information: what it is, current state, usage guidance, and a clarifying disclaimer. It is dense but not padded, with the core definition leading.

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 provides a complete picture by referencing the stable tool's response shape and clarifying its equivalence. The experimental context, current status, and fallback behavior are all covered, making it sufficiently complete for a router.

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

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

Schema covers all 6 parameters with descriptions and aliases (100% coverage), so the description need not add parameter detail. No additional semantic value is provided beyond the schema, but none is required.

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

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

The description clearly defines the tool as a beta version of ask_pipeworx, a universal router, and distinguishes it from the stable sibling by highlighting experimental routing improvements. The verb+resource is explicit 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?

Explicitly instructs when to use ('when you want the newest routing'), names the stable alternative (ask_pipeworx), and clarifies that results are compared against it. Also notes current matching behavior, giving clear context.

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

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

Beyond the readOnly/idempotent annotations, the description discloses exact return shapes, success vs. refusal behavior, the full refusal_reason enum, the extra LLM call cost, and the constraint that answers only come from tool result content. This gives the agent a precise behavioral model without contradiction.

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

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

The description is front-loaded with purpose, then delivers the return contract, refusal reasons, and usage guidance in a dense, non-redundant format. Every sentence contributes unique value, and the structure makes the tool easy to evaluate quickly.

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 fully documents the success response fields, the refusal response fields, all possible refusal reasons, and the exact conditions for use. Combined with clear cost tradeoffs and source-routing context, the description is self-sufficient for correct tool selection and invocation.

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

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

The schema already covers all parameters with 100% description coverage, including the primary 'question' and five aliases. The description adds no parameter-specific semantics beyond what the schema states, 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 clearly identifies this as a grounded, hallucination-resistant answer mode that routes like ask_pipeworx but extracts answers strictly from tool results. It distinguishes itself from siblings by emphasizing the verification and refusal behavior, making the tool's 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?

Explicit usage guidance is provided: use when answers will be quoted, cited, or acted on, especially for high-stakes domains like financial, legal, or medical facts. It also explicitly states when to prefer ask_pipeworx (casual lookups) due to the extra LLM call cost, giving clear alternatives and tradeoffs.

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

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

Annotations already declare readOnly/idempotent/non-destructive; the description goes far beyond by detailing fan-out sources, response shapes, resolver match confidence contract, safety short-circuit mechanisms (status:'low_confidence_match', 'market_closed_or_inactive'), news fallback fields, and resolution-rule risks (cancellation_rule, flat-50¢ void settlements).

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 extensively detailed and well-structured with ALL-CAPS sections, but it is far longer than needed for an agent to select and invoke correctly. It front-loads purpose, but many details (e.g., specific fan-out examples, news fallback mechanics) could be condensed or moved elsewhere.

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 documents response shapes, resolver contract, parent_event extractor, news fields, safety statuses, and cancellation-rule risk. Complex behavior is well covered, including edge cases and blocking paths, making it complete for an agent.

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

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

Schema covers all 3 parameters with clear descriptions (100% coverage). The description adds examples of market input forms and explains quick vs thorough fan-out, but these are largely redundant with the schema. It doesn't add crucial new semantics beyond schema.

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

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

Description clearly states the tool's specific purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further specifies input types (slug, URL, question text), classifiers, and use cases, making it distinct from generic research 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?

Provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Also gives domain-specific guidance like 'Check this before sizing sports/esports/event-occurrence bets' and 'ALWAYS inspect these before trusting the analysis block.' However, it doesn't name alternative tools or explicit when-not-to-use conditions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds rich behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return format with citation URIs. No contradiction.

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

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

Though lengthy, every sentence carries essential information: query pattern, preferred usage, entity-type specifics, data sources, sorting behavior, and return format. It's front-loaded with examples and efficiently structured 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?

Despite no output schema, the description explains what the response will contain (paired data + citation URIs) and how results are ordered. It covers all key aspects an agent needs to invoke and interpret the tool correctly, especially given the two-parameter 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%, but the description adds deeper meaning by explaining what each type yields: company pulls financial metrics, drug pulls adverse-event/trial data. It also clarifies the values parameter with examples and constraints, going beyond the schema's basic descriptions.

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

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

The description clearly states it performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with explicit query examples. It distinguishes itself from sequential single-pack lookups, making 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?

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a direct when-to-use instruction and naming the alternative. Examples of trigger phrases like 'X vs Y' and 'rank these companies' give concrete usage context.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive behavior. The description adds extensive behavioral details: parallel decomposition into facets, routing to 5,366 tools, semantic excerpting, gaps[] never invented, contradictions[] for deeper depths, hop fields, latency expectations, and authentication requirements. This far exceeds the annotations and provides a rich behavioral model.

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 front-loaded with critical account and usage information, and every sentence contributes unique value. It could be better structured (e.g., bullet points) to aid scanning, but given the tool's complexity, the length is justified. Loses one point for being somewhat dense and rambling.

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 covers purpose, usage, prerequisites, alternatives, limitations, behavior, parameters, output structure, and performance expectations. Despite having no output schema, it thoroughly describes the findings packet including evidence, confidence, source, fetched_at, citations, gaps[], and contradictions[]. This is exceptionally complete for a complex research 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 significantly enhances parameter understanding. For 'question', it explains that broad/multi-part questions are fine and decomposition is the point. For 'depth', it elaborates on the exact behavior of each enum value (quick vs standard vs thorough), including gap recovery, contradiction scans, and the paid plan requirement. This goes beyond the schema descriptions.

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

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

The description opens with a clear directive: 'Grounded multi-source research across Pipeworx's 1396 STRUCTURED data sources...' using a specific verb ('research') and resource, immediately distinguishing itself from open-web search. It also explicitly differentiates from sibling tools like ask_pipeworx, making the tool's 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 provides explicit usage guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and notes the account/plan requirements. It clarifies when deep_research is appropriate and when alternatives are better, going well beyond a simple purpose statement.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds valuable behavioral context beyond annotations: it explains the return format (top-N results with names, descriptions, full schemas, curated examples), the fact that results are 'ready to call directly,' and the strategic guidance to call it first. This enriches the agent's understanding of how the tool behaves without contradicting any annotations.

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

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

The description is front-loaded with the core purpose in the first sentence, and each subsequent sentence adds distinct value: when to use, what it returns, and strategic placement. The list of domains is somewhat long but directly aids the agent in assessing relevance. It is slightly verbose but not bloated, earning a 4.

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

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

The tool has no output schema, so the description must explain return values, and it does: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It also covers input style, usage context, and strategic guidance. For a discovery tool with straightforward parameters, this is 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%, so all parameters are already described in the schema. The description adds no additional parameter-level semantics beyond the schema, other than implicitly reinforcing that 'query' is a natural language description. Per the rubric, a baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource: 'Find tools by describing the data or task.' It clearly distinguishes itself from sibling tools like search_datasets or query_layer by focusing on tool discovery, not data retrieval. The scope is further clarified with a list of domains (SEC filings, FDA drugs, etc.), leaving no ambiguity about what the tool does.

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

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

The description explicitly states when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implies when not to use it (when you already know the specific tool or need a direct answer), providing clear context relative to alternatives.

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

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

Annotations already show readOnly/idempotent/non-destructive, and the description adds valuable behavioral context: parallel fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF; the PatentsView API sunset and soft-fail behavior; GDELT→GNews fallback; and the limitation to US public companies with ticker/CIK input.

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

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

The description is a single dense paragraph, but it is front-loaded with natural-language examples and the core purpose. Every clause adds useful information, though the opening quotes and the 'ALWAYS PREFER' redundancy could be trimmed slightly without losing meaning.

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

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

Without an output schema, the description fully enumerates the return payload: cik, company_name, recent_filings with URIs, fundamentals, patents, news mentions, and LEI. It also covers known degradation (patent sunset) and fallback behavior, making the tool's behavior clear enough for an agent to decide and 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 description coverage is 100%, so the baseline is 3. The description adds concrete examples ('AAPL', '0000320193'), reinforces zero-padding, and reiterates that names are unsupported, which helps disambiguate input format beyond the schema enum.

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 building a 'full cross-source profile of a US public company in ONE parallel call,' with an explicit verb ('profile'), resource ('US public company'), and scope. It differentiates from siblings by naming the single-pack SEC/XBRL/news lookups it replaces and by pointing to resolve_entity for name inputs.

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

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

The description gives explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides a clear exclusion: 'names not supported (use resolve_entity first if you only have a name).'

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 idempotentHint=true, covering the key behavioral traits. The description adds rationale for use but no additional operational details such as permanence or return values. This is acceptable but not overly rich.

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

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

Three sentences, front-loaded with the core action, and no wasted words. Every sentence serves a purpose.

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

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

This is a simple one-parameter tool with annotations covering its destructive and idempotent nature. The description includes usage guidance and pairing, which is sufficient. Minor missing details like prerequisites or behavior for non-existent keys are covered by idempotentHint.

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

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

The schema has 100% coverage for the single parameter 'key' with the description 'Memory key to delete'. The description mentions 'by key' but adds no extra meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific action ('Delete a previously stored memory by key') with a clear verb and resource, distinguishing it from siblings like remember and recall.

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

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

The description explicitly lists when to use the tool ('when context is stale, the task is done, or you want to clear sensitive data'), giving clear context. It doesn't mention when not to use it or an alternative for deletion, but pairing with remember and recall is implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds behavioral context by explaining that it fetches a page, extracts specific elements, and returns a single text blob in llms.txt format. This goes beyond the annotations without contradicting them.

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

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

The description is concise and front-loaded, covering purpose, process, output, and use cases in two sentences with no wasted words.

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

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

This is a simple tool with good annotations and a complete schema. The description fully covers inputs, behavior, output format, and intended use cases. No output schema exists, but the description explicitly states the return format ('single text blob') and its target location.

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

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

Schema description coverage is 100% and both parameters are documented in the schema. The description does not add extra parameter-level detail (e.g., what max_links controls), so the 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 states a specific verb ('generate'), a concrete artifact ('production-ready llms.txt file'), and the process ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format'). It clearly distinguishes this tool from siblings like scan_competitor_ai_presence by focusing on generating the file itself.

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

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

The description lists explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor') and mentions the output format. It lacks an explicit 'when not to use' but provides sufficient context for when to select this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the operation's safety is known. The description adds context about what the tool returns (schema fields, geometry, count, capabilities), providing useful behavioral transparency beyond the structured annotations.

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

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

The description is a single, front-loaded sentence that concisely conveys the tool's purpose and key outputs without unnecessary verbosity. Every word contributes meaning.

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

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

For a simple one-parameter tool with rich annotations and no output schema, the description provides enough information about the returned data (fields, geometry, count, capabilities) to make the tool's behavior clear. There is no notable missing context for the agent to use it correctly.

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

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

The input schema has 100% coverage for the single 'url' parameter with a clear description and example. The description's mention of 'by url' aligns with the schema but adds no additional semantic detail beyond it, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action (Get), the resource (ArcGIS Feature/Map Service layer's schema), and the specific outputs (fields, geometry type, record count, capabilities). It is specific enough to distinguish from sibling tools like query_layer, which would be used for querying data rather than schema.

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

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

The description implies clear usage context: use this tool when you need schema details of an ArcGIS layer. It does not explicitly mention when NOT to use it or name alternative tools, but the purpose is unambiguous enough for an agent to choose it appropriately.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds context beyond that by clarifying that only active subscriptions are returned by default (with include_inactive to change that) and by listing the specific fields returned, which is valuable behavioral detail.

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 filler. The first sentence states the core purpose and return value, the second provides usage context. Every word earns its place.

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

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

Given the simple tool (one optional boolean param, no output schema), the description covers purpose, scope, return fields, and use cases. It is self-contained and sufficient for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the include_inactive parameter is fully documented in the schema. The description does not add additional parameter semantics; it only implies default behavior via 'active subscriptions', which the schema already states. 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 uses the specific verb 'List' with the resource 'subscriptions', scoped to 'the caller's active subscriptions'. It also enumerates return fields (id, type, params, created_at, last_fired_at, fire_count), clearly distinguishing it from mutation 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 states concrete use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. This implies alternatives (subscribe/unsubscribe) but does not explicitly name them, so it falls short of a 5.

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 offer no safety hints (all false), so the burden falls on the description. It discloses rate limiting (5 per identifier per day), that it's free and doesn't count against tool-call quota, and that the team reads digests daily. However, it doesn't describe the response/return behavior after submission, which would be useful.

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

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

The description is a single well-organized paragraph that front-loads the purpose and then efficiently covers usage scenarios, content guidance, and constraints. No redundant sentences; every clause earns its place.

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

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

For a 3-parameter feedback tool with no output schema, the description covers all necessary context: when to use, what to include, constraints, and downstream impact. It is complete enough for an agent to invoke correctly without further clarification.

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 detailed per-parameter descriptions, so baseline is 3. The description adds extra semantic guidance for the message parameter (describe in terms of tools/packs, don't paste user prompt), which goes beyond the schema. This justifies a 4.

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

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

Description clearly states the verb (tell/send) and resource (Pipeworx team feedback), and explicitly outlines the categories (bug, feature, data_gap, praise). It distinguishes itself from sibling data-query tools like ask_pipeworx by focusing on feedback rather than information retrieval.

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

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

Provides explicit when-to-use conditions: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also specifies what to include (tool/pack context) and what not to include (end-user prompt), plus constraints (rate limit, free, no quota).

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

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

Annotations already mark it read-only, open-world, and idempotent, and the description adds valuable behavioral context: it's a self-aggregating signal derived from CF analytics-engine, includes no PII, and has caching delays of 5 minutes to 1 hour. This goes beyond the structured metadata.

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

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

The description is front-loaded with the core purpose, then provides a structured list of use cases, and closes with transparency notes. Every sentence adds distinct value, and the formatting (numbered list, dash-separated data note) aids readability.

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

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

For a simple one-parameter read-only tool with excellent annotations, the description covers everything an agent needs: what it returns, when to use it, and how it behaves (caching, PII-free). The absence of an output schema is mitigated by the explicit mention of 'top tools, top packs, and total call volume'.

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

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

The schema documents the single 'window' parameter with 100% coverage, including its enum values and a description of what shorter vs. longer windows represent. The main description only restates the enum values, so it doesn't add meaning beyond the schema; baseline 3 is appropriate.

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

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

The description opens with a clear, specific statement of what it provides: a view of what other agents are calling on Pipeworx, including top tools, top packs, and total call volume. This distinguishes it from siblings like discover_tools by focusing on aggregated trending signal rather than general discovery.

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

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

The description includes an explicit 'Useful for' list with three concrete use cases, giving clear guidance on when to invoke this tool. It doesn't name alternatives or state when not to use it, but the use-case framing is strong context for agent selection.

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

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

Annotations are limited to read-only/open-world/idempotent, but the description adds rich behavioral detail: the fill-check warning ('realizable_edge_pp ≤ 0... do not trade it'), the partition filter logic with placeholder slugs, the semantic similarity threshold (≥0.30 Jaccard), and the specific signals emitted (BUY/SELL EVERY LEG). This significantly exceeds annotation data.

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 (~300 words) and dense, but the use of section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose sentence improve scannability. Some redundancy exists (e.g., repetitive phrasing 'pass a...' vs 'for...'), and it could be tightened, but nothing is irrelevant.

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

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

Given the tool's complexity and lack of an output schema, the description thoroughly covers return values (opportunities[] fields, partition_check structure), behavioral caveats (fill check, placeholder filtering), and mode differences. It leaves little ambiguity about what the tool does and what it returns.

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 its descriptions are decent, but the tool description greatly enriches them. It provides concrete examples ('fed-decision-may-2026'), explains what each mode does (walks child markets, searches related events), and clarifies that no args triggers a trending scan. This goes well beyond the schema's basic 'use this if...' phrasing.

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

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

The description opens with a clear, specific purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes the tool from siblings like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection through these specific methods, and further clarifies sub-modes (event vs topic).

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

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

It gives explicit when-to-use guidance: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also names an alternative: 'For custom sizing use polymarket_fill_risk.' The distinction between event and topic modes is thoroughly explained.

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, and idempotentHint. The description adds substantial behavioral context beyond these: caching behavior ('Cached 1h at the KV level keyed on all knobs'), response structure with diagnostics, the 24-hour move warning, placeholder-slug filters, and 'rare-by-design' concentrated longshots. It also explains why segments may be empty and how FED candidates are excluded. 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 a single, dense block of text with no bullet points or headings. It contains valuable information but is excessively long and could overwhelm an agent. The front-loaded opening is strong, but the overall structure lacks readability. Every sentence earns its place, but the presentation is not appropriately sized for quick parsing.

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

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

Given the tool's complexity and absence of an output schema, the description thoroughly explains return values: every opportunity carries edge_pp_net, kelly_fraction, kelly_fraction_half, etc., and the top-level response includes by_segment, fed_candidates, and _diagnostics. It also covers edge cases like empty segments and knob effects. This is nearly exhaustive for the tool's 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?

Schema coverage is 100%, so baseline is 3. The description adds meaningful beyond-schema semantics, especially for min_partition_leg_kelly (explains why min_kelly doesn't apply to partition arbs and how per-leg Kelly works) and the tradeable-edge knobs (min_liquidity/max_spread_pp). It also explains slippage context ('Polymarket has zero trading fees... bid/ask + thin depth typically eats 20-50bp per trade'). This exceeds the baseline.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly states the tool's purpose and differentiates it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on edge discovery for betting decisions. The phrase 'Built for "what should I bet on today"' reinforces the intended use case.

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

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

The description provides clear context: 'agents discover opportunities without paging hundreds of markets' and notes that FED bets are excluded due to unreliable signal. However, it does not explicitly name alternative tools or provide when-not-to-use guidance. The intended use case is clear, but exclusions are implied rather than stated.

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

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

Annotations already signal a safe read-only operation, but the description adds substantial behavioral context: 60-day snapshot TTL, starting point of history, cache-miss snapshot gaps, and decay computed from daily closes (not intraday). These details go well beyond the annotations and are especially valuable for interpreting results.

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 well organized: purpose first, then args, response shape, and limits. Even though it is long, every section earns its place because there is no output schema to carry the response-format 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 no output schema, the description fully specifies the returned components (tracked, expired, snapshot_dates), their meaning, and important caveats about data gaps and history limits. This is sufficient for an agent to understand what the tool returns and how to interpret 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?

Schema coverage is 100%, with both parameters already described in the input schema. The description repeats defaults and adds 'max 30' but does not materially extend the semantic meaning provided by the schema beyond restating 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 tool provides edge persistence and decay telemetry from daily snapshots and answers a specific temporal question ('how long has this edge existed and is it shrinking?'). This distinguishes it from a live edges tool and makes the 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 frames the appropriate use case by contrasting fresh wide edges with older ones, implying when persistence/decay insight is needed. It does not explicitly name alternatives or state when not to use it, but the context is 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 establish this is read-only, open-world, idempotent, and non-destructive. The description goes beyond this by detailing the exact order-book walking behavior, return fields for both modes, and failure modes like thin books and forced directional risk, which are not captured by 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?

While the description is long, it is densely packed and each clause contributes unique operational guidance. It is front-loaded with the core purpose, though a wall-of-text format slightly reduces scannability. The complexity of two modes justifies the length, but it could be restructured for readability.

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

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

With no output schema, the description fully enumerates returned fields for both modes—including `top_of_book`, `vwap_fill_price`, `slippage_pp`, `shares_filled`, `max_fillable_usd`, `verdict` and basket-specific fields like `capture_ratio`, `profit_usd`, `thin_legs[]`, `max_clean_notional_usd`, `forced_directional_risk`. It also covers parameter semantics and usage timing, making it self-contained.

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

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

There are 4 parameters with 100% schema coverage, so baseline is 3. The description adds substantial semantics: it explains that `market` and `event` are mutually exclusive modes, defines `side` defaults per mode, and interprets `size_usd` differently for single-market vs basket (spend/target proceeds vs settlement notional). This goes far 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 opens with a specific verb phrase 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which precisely states the tool's function. It clearly distinguishes between single-market and basket modes, setting it apart from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly names when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' This directly addresses alternatives and provides exclusion criteria, such as noting partial fills convert arb into unhedged directional positions.

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 (readOnly, idempotent, openWorld) by disclosing critical behavioral details: the compatibility_warning conditions, temporal_alignment impact on spread validity, skipped_cross_type/subtype counters, and the nuance that matched_pairs:0 with skipped_cross_type:0 implies semantically unrelated events. It also explains that the tool proactively reports when bet shapes are non-equivalent, which is high-value behavioral transparency.

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

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

The description is dense and lengthy, but it is logically structured with labeled sections: 'TWO MODES,' 'RESPONSE,' 'SAFETY FIELDS,' and temporal alignment. Every sentence conveys important operational detail, and key terms are highlighted in caps. It is slightly verbose but earns its length given the tool's complexity.

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

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

With no output schema, the description fully explains the return structure: leg-by-leg prices, spread in percentage points, compatibility_warning, matched_pairs, skipped_cross_type/subtype, and temporal_alignment. It covers edge cases (e.g., non-equivalent bet shapes, unrelated events) and sets expectations about real-world spread availability. For a tool with three optional parameters and high complexity, this is 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?

The schema already covers 100% of parameters with descriptions, so baseline is 3. The description adds meaning by explaining how parameters interact: the 'topic' is a pre-mapped shortcut, while 'kalshi_event_ticker' and 'polymarket_event_slug' 'Override the topic-mapped side.' This clarifies the override semantics and gives concrete examples, adding value beyond the schema alone.

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

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

The description opens with a precise statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly identifies the tool's function (calculating spread) and its resource (two venues), and it distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparison. The two-mode breakdown further specifies how the tool operates.

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

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

The description explains when to use the tool: for comparing the same question across Kalshi and Polymarket, and it details two modes (pre-mapped topics vs explicit event tickers). It also warns that 'most pre-mapped topics return compatibility_warning today' and 'pre-mapped ≠ tradeable,' giving practical guidance on expected outcomes. However, it does not explicitly contrast with sibling tools by name, so it stops short of a full 'when-not-to-use' differentiation.

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, open-world, idempotent, and non-destructive. The description adds valuable behavioral context beyond this: it returns attribute rows and geometry, supports SQL-like queries, and the sampling tip reveals pagination and field-selection behavior. It does not contradict the annotations.

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

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

The description is extremely concise: two sentences that front-load the purpose, then provide a useful example. Every word earns its place, with no filler or repetition of schema 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 6 parameters, 100% schema coverage, and strong annotations, the description is quite complete. It states the return type (attribute rows and geometry), references the source of the url, and gives a sampling strategy. It could elaborate on pagination or error behavior, but those are covered by the schema and annotations, leaving only minor gaps.

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

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

Schema coverage is 100%, with all parameters well-described in the input schema. The description does not add new meaning to individual parameters beyond listing them, which is mostly redundant. However, the sampling tip provides a practical use case that adds moderate semantic value, so it stays at the baseline 3.

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

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

The description clearly states a specific action: 'Query an ArcGIS Feature Service / Map Service layer by its url', which is a distinct verb+resource combination. It also distinguishes from siblings by referencing search_datasets and specifying the output (attribute rows and geometry), making its 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 clear context by noting the url comes from search_datasets, implying the intended workflow. It also offers a practical usage tip (sampling with where="1=1" and out_fields="*"). However, it does not explicitly exclude alternatives like layer_info or search_within, so it lacks formal when-not-to-use guidance.

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

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds meaningful context beyond this by explaining scoping to an identifier (anonymous IP, BYO key hash, or account ID), which is crucial for understanding data isolation. It also mentions the listing behavior when key is omitted.

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 use case. Each sentence adds essential information: retrieval/listing, usage rationale, scoping, and paired tools. No wasted words.

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

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

For a simple single-parameter retrieval tool, the description fully covers what the tool does, when to use it, its scoping behavior, and its relationship to sibling tools. No output schema is present, but the description sufficiently conveys expected return behavior (list or value).

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

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

The schema covers the single optional key parameter fully (100% coverage). The description adds value by illustrating example keys (user's target ticker, address, research notes) and clarifying the key-omission behavior for listing all keys, enhancing semantic 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 retrieves a value saved via remember or lists all saved keys when the key is omitted. It distinguishes itself from siblings by explicitly pairing with remember and forget.

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

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

The description provides explicit usage context: looking up previously stored agent context to avoid re-deriving it. It also names sibling tools for adjacent actions (remember to save, forget to delete), giving clear guidance on when to use this tool versus alternatives.

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

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

The description discloses a mutating side effect (mark_read:true flags events read), which contradicts the readOnlyHint:true annotation. This is a clear annotation contradiction, so the score is 1.

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

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

The description is concise and well-structured: purpose, return details, filtering, side effect, and alternative endpoint are all covered in two sentences with no wasted words.

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

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

The description covers return values, filtering, side effect, and alternative access. Without an output schema, it explains what each event carries. It does not mention pagination or errors, but the schema and annotations cover most 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%, so parameters are already documented. The description adds meaningful examples (type "sec_8k", since ISO timestamp) and explains the consequence of mark_read, 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 pulls fired events from the subscription feed, with specific return contents. It distinguishes itself from sibling tools like recent_changes and list_subscriptions by focusing on alerts.

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

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

The description gives clear context that polling works fine and points to an alternative direct endpoint for scripts/dashboards. It lacks explicit comparisons to sibling tools but provides a concrete alternative and implied use cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral detail: the fan-out to multiple sources, GDELT→GNews fallback on rate-limits/5xx, USPTO PatentsView API sunset soft-fail, and the structured return shape (changes[], total_changes, citation URIs). This goes well beyond the annotations and gives the agent a clear model of runtime 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 dense but every sentence earns its place: usage examples, source list, fallback behavior, date formats, return structure, and a pointer to the sibling tool. It is longer than the TDQS high-watermark example, but the complexity of the tool justifies the length. The structure is efficient and front-loaded with query patterns.

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

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

For a tool with no output schema and significant behavioral complexity, the description covers all necessary aspects: what it returns (structured changes grouped by source, total_changes, citation URIs), failure modes (GDELT fallback, USPTO soft-fail), accepted date formats, and the boundary with entity_profile. The agent can confidently decide when to invoke this tool and what to expect as 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% (all three parameters described), so the baseline is 3. The description adds value by explaining `since` formats with examples (ISO vs '7d', '30d', '3m', '1y') and specifying that `value` can be a ticker or zero-padded CIK. It also contextualizes the `type` parameter as 'company' only. This is helpful but not transformative given the schema already defines each parameter.

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

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

The description clearly states the tool returns a 'change feed for a company in the last N days/weeks/months' and explicitly differentiates it from entity_profile ('Use entity_profile instead when you want the static profile'). It names the specific sources (SEC EDGAR, GDELT/GNews, USPTO) and the single-call fan-out behavior, 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?

Provides explicit usage guidance with natural language examples ('What's new with X', 'latest on Y') and a clear alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also clarifies the `since` parameter's accepted formats and typical values ('Use "30d" or "1m" for typical monitoring').

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

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

Annotations indicate non-read-only and idempotent, but the description adds valuable context about key-value scoping, user-based persistence, and the 24-hour retention for anonymous sessions. 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 three sentences and front-loads the primary purpose. It includes usage examples and persistence details without being bloated. Slightly more detail than strictly necessary, but each sentence earns its place.

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

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

For a simple 2-parameter tool with no output schema, the description covers purpose, usage, persistence, and sibling relationships. It is sufficiently complete for an agent to select and invoke the tool correctly without additional information.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra meaning beyond the schema; it mentions key-value pairs but doesn't elaborate on format or additional constraints. The schema already provides examples, so this is adequate.

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

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

The description opens with a specific verb and object: 'Save data the agent will need to reuse later.' It clearly distinguishes itself from sibling tools by explicitly mentioning pairing with recall for retrieval and forget for deletion, making the purpose unambiguous and differentiated.

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

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

Provides clear when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference') and states the alternative tools (recall, forget). This fully satisfies the dimension.

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 readOnly, idempotent, and non-destructive hints. The description adds that each call cascades through multiple lookup endpoints and details the exact return fields and citation URIs per type, going beyond the annotations without contradiction.

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

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

The description is relatively long but every component earns its place: example queries, use directive, supported types with output details, and internal context. It is front-loaded with purpose and examples, and the SUPPORTED TYPES section aids scanning.

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

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

With no output schema, the description explicitly lists return values for each entity type, including citation URIs, and explains the internal cascade that replaces multiple lookups. This gives a complete picture for the agent to invoke correctly, though error handling is not covered.

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, but the tool description enriches parameter meaning by specifying accepted input formats (ticker, CIK, name; brand/generic) and auto-disambiguation behavior. This adds value beyond the raw 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 verb ('resolve') and resource ('user-spoken NAME to the canonical/official identifier'), with concrete example queries. It distinguishes itself from siblings by positioning it as the first step when needing an ID, and lists supported entity types.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', giving a clear directive for when to use. It does not name alternative tools or explicit when-not scenarios, but the context is strong enough for an agent to decide.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is known. The description adds valuable context by explaining that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with confidence and signal density. This goes beyond 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 three sentences long, front-loaded with the core purpose, and every sentence adds value—purpose, mechanics, use case, and output. No redundancy or fluff.

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

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

For a tool with 4 parameters, one required, and no output schema, the description covers the main behavioral contract: what it does, how it works (probes via ai_visibility_check), when to use it, and what output looks like. Some edge-case details (e.g., handling of missing entities) are omitted, but the description is sufficiently complete for selection and invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning by noting 'First entry treated as the "subject" for narrative; rest are competitors,' which clarifies the role of the entities parameter. It also hints at the models parameter with 'your brand + N competitors,' reinforcing the schema's descriptions.

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

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

The description clearly states a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes itself from sibling ai_visibility_check by emphasizing 'multiple entities' and 'side-by-side,' and further details ranking and output. This is unambiguous and differentiates the tool well.

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: 'Useful for competitive AI-marketing audits' with an example. It implies this tool is for comparing multiple entities vs. a single-entity check, but does not explicitly mention alternatives or when-not-to-use. Context is strong, so it earns a 4.

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, the description discloses that it fans out across two services, returns a structured summary, and degrades gracefully on partial failures. It specifically mentions that bundlephobia's first measurement can take 5-30 seconds and that sources_failed will list it if it times out, which is valuable 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 longer than average but every sentence provides useful information: purpose, use cases, output fields, ecosystem scope, and failure behavior. It is front-loaded with the core purpose, and the details are structured logically.

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 composite tool with no output schema, the description thoroughly explains the returned summary block fields, per-advisory details, alternative versions, and failure handling. It covers NPM-only limitation and references deps.dev for other ecosystems, making the agent fully informed.

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 helpful descriptions for package and version, including scoped package acceptance and version defaulting. The description does not add significant parameter detail beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose as a composite 'should I add this npm package to my project' check, combining deps.dev and bundlephobia data. It differentiates from alternatives by explicitly noting the NPM-only scope and directing other ecosystems to deps.dev:version.

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 given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also notes ecosystem limitations and advises using deps.dev:version for non-NPM packages, plus warns about potential bundlephobia timeout delays.

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 this as a read-only, non-destructive, idempotent operation. The description adds meaningful context by listing the exact return fields (name, summary, record_count, owner/org, Feature Service URL) and the scope of datasets (parcels, zoning, public works & city services). It does not mention potential limitations like rate limits or pagination, but given the annotation coverage, a 4 is appropriate.

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

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

The description is two sentences, front-loaded with the action and resource, and every word adds value. It efficiently communicates the tool's purpose, return data, and downstream usage without any 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 search tool with three optional parameters and no output schema, the description is complete. It explains the return values, the scope, and how to use the results, making it sufficient for an agent to decide when and how to invoke the tool.

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

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

The input schema covers all three parameters with clear descriptions (limit, query, org_id), achieving 100% schema description coverage. The description itself adds no additional parameter semantics beyond what's already in the schema, so the baseline score of 3 is justified.

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 ('Search') and resource ('City of Henderson GIS open geospatial datasets'), and it distinguishes the tool from siblings by explaining that it returns Feature Service URLs to be used with query_layer/layer_info. This makes the purpose unambiguous and differentiates it from other tools.

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

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

The description clearly implies when to use this tool: to find datasets, after which you pass the returned URL to query_layer or layer_info. It provides a direct follow-up path but does not explicitly state exclusions or alternative search tools, so it falls short of a perfect 5.

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 technical details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging. Annotations already declare read-only/idempotent, so this adds genuinely useful behavioral context about how results are computed and returned.

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

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

Every sentence earns its place: function, use case, pairing with sibling, and technical constraints. No filler or redundancy; the structure front-loads the core purpose and then adds context.

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

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

With no output schema, the description fully explains return values (passages with character offsets and similarity scores) and highlights the truncation flag behavior. It also covers limits and use case, making it self-sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, giving baseline 3, but the description adds meaningful parameter context: example queries for the 'query' field, the truncation cap for 'text', and clarifies that 'limit' controls top-N passages. This goes beyond the schema descriptions.

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

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

The description states a specific verb+resource: 'Semantic search INSIDE a fetched record' and clearly defines inputs (text + query) and outputs (top-N passages with offsets/scores). It distinguishes itself from siblings by emphasizing the 'inside a fetched record' scope, contrasting with search_datasets or 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 when to use: 'Use when the record is too big to cram into the prompt' and describes the benefits (saves context, lets agent verify verbatim quotes). It also names a complementary alternative, ask_pipeworx_grounded, and explains how they pair together.

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

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

Beyond the annotations (readOnlyHint false, idempotentHint true, etc.), the description discloses auth/account constraints, persistence behavior, return of subscription id, feed always-on, and delivery-specific limits (phone verification, 10/day SMS cap). It adds meaningful context about operational side-effects without contradicting the annotations.

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

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

The description is a single paragraph but densely packed with relevant information, front-loaded with the core action and return value. Each clause covers a distinct aspect (types, delivery, prerequisites). It is not overly verbose, though it could be more scannable with bullets; still, every sentence earns its place.

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

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

For a tool with 3 params, nested objects, and 5 enum types, the description covers supported types, delivery channels, auth prerequisites, and return value. The only gap is the omission of the webhook delivery channel in the description text (though the schema covers it), and it does not explicitly mention management through sibling tools. Overall, it is sufficiently complete.

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

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

The input schema already has high coverage (100%), but the description adds practical examples and semantic clarifications, such as 'items:["5.02"] = officer change' and specific params for each type (topic:'fed', series_id:'UNRATE'). This goes beyond the schema's generic descriptions and helps the agent understand parameter combinations.

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

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

The description opens with a specific action: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly names the resource ('subscription'), the action ('create'), and the qualifying context ('proactive monitoring', 'live-data event stream'), and states the return value ('Returns the new subscription id'). This distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides usage context by noting the OAuth account requirement ('anonymous + BYO cannot persist subscriptions') and implicitly contrasts the push subscription with pulling via 'recent_alerts or GET registry.pipeworx.io/alerts.json' for the always-on feed. It does not explicitly name alternatives for cancellation or listing, but the context is 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?

The description goes beyond the annotations by disclosing the return shape ('category-bucketed example questions ... with the exact tool + argument shape'), the effect of calling with no arguments vs a topic, and its role as an onboarding entry point. It also notes it draws from 'the live catalog of thousands of tools,' adding context not apparent from the schema or 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 compact: four sentences, each serving a distinct purpose—example queries, core purpose and return format, invocation details, and when-to-use guidance. It is front-loaded with natural-language questions that immediately convey the tool's utility without 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 is fully self-contained for a simple, one-parameter tool with no output schema. It explains what the tool returns, the categories it covers, optional topic focusing, and when to use it first. No critical information is missing for an agent to call it correctly.

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

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

The schema already documents the 'topic' parameter with allowed values and the behavior when omitted. The description adds examples ('finance', 'pharma', 'betting') but does not materially extend the semantic meaning. Since schema coverage is 100%, a baseline of 3 is appropriate; the description adds minimal value beyond what the schema already states.

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 a specific verb+resource+scope: it is 'the onboarding entry point' that 'Returns category-bucketed example questions' with exact tool+argument shapes. This distinguishes it from siblings like ask_pipeworx or discover_tools, which serve different query/discovery purposes.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It even names alternative tools (ask_pipeworx, entity_profile, compare_entities), providing clear context for when to use this tool instead of others.

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

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

The description goes beyond annotations by explaining that ownership is enforced and that the row is deactivated (soft delete) rather than deleted, preserving historical events via recent_alerts. This is valuable behavioral context that annotations do not capture, and it is consistent with idempotentHint=true and destructiveHint=false.

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

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

The description is compact (three sentences) and front-loaded with the core action. Every sentence provides useful information—action, ownership constraint, and side-effect explanation—without redundant 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 a single parameter and no output schema, the description covers purpose, the key constraint, and the important side effect (deactivation vs. deletion). It is sufficiently complete for an agent to invoke it correctly and understand the outcome.

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?

Although the schema already documents the 'id' parameter well (including provenance from subscribe), the description adds a meaningful semantic constraint: ownership enforcement. This helps the agent understand that only own subscriptions can be cancelled, which is not in the schema.

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

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

The description uses a specific verb ('Cancel'), identifies the resource ('a subscription'), and specifies the key input ('by id'). It clearly distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

The context is clear: this tool cancels an existing subscription. It does not explicitly name alternatives or exclusion criteria, but the purpose is unambiguous and the ownership constraint is stated, giving adequate guidance for selection.

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

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

Annotations cover safety traits (read-only, open-world, idempotent, non-destructive), and the description adds substantial behavioral detail: the SEC/XBRL fast path, fallthrough to a grounded pipeline, return of a verdict with verbatim evidence and reasoning, and replacement of 4–6 sequential calls. This goes well beyond what the annotations alone provide.

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

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

The description is dense but every sentence earns its place: trigger phrases, scope, routing, return format, and efficiency gain. It is front-loaded with the purpose and immediately gives usage examples, with no redundant 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 2-parameter tool with no output schema, the description fully covers the return contract (verdict types, actual value, citation, reasoning) and the decision logic. It is complete enough for an agent to select and invoke the tool correctly without additional 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?

The schema already provides detailed descriptions for both parameters (claim and tolerance_pct), so the description adds limited new meaning. It reinforces with a concrete claim example but does not materially extend the schema's parameter explanations.

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

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

The description opens with concrete trigger phrases and names the exact operation: natural-language claim verification against authoritative sources. It clearly distinguishes from sibling tools by specifying the claim-checking use case and by describing the internal routing for company-financial vs. other claims.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing strong contextual guidance. It also describes how different claim types route through different pipelines, but it does not name alternative sibling tools or explicitly state when not to use this tool.

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