Arcgis Stlouiscounty

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds behavioral context: probing multiple models, scoring 0-100, returning per-model fields (score, confidence, signals, raw_response), and the BYO key arrangement for Anthropic. This goes beyond annotation basics.

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 purposeful sentences: core function + return, model/API details, and use cases. No redundancy; every sentence adds unique 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?

The description covers key aspects: purpose, model options, API key need, return structure, and examples. With no output schema, it provides enough detail for an agent to understand results. Minor omissions (e.g., caching behavior, authentication requirements) are acceptable given 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 adds value: it notes the default model for 'models', explains when '_apiKey' is required, and clarifies that 'context' disambiguates common names. This helps the AI agent use parameters correctly.

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

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

The description uses specific verbs ('probe', 'score visibility') and clearly defines the resource (LLMs for entity knowledge). It distinguishes from sibling tools like 'scan_competitor_ai_presence' by being general-purpose, covering brands, products, people, or topics.

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 (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains model options (default Workers AI, optional Anthropic with API key). It lacks explicit exclusion criteria but provides sufficient context for appropriate use.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context by explaining the internal routing mechanism ('routes the question to the right one of 5,564 tools') and the output format ('stable pipeworx:// citation URIs'). It does not contradict annotations. While the annotations already cover the safety profile well, the description enriches understanding of how the tool behaves internally.

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 ideal (several paragraphs) but well-structured: opening with a bold priority statement, then listing capabilities, usage scenarios, examples, and escalation paths. Every sentence provides actionable guidance. The front-loading of 'PREFER OVER WEB SEARCH' is excellent. Slight verbosity prevents a 5, but it remains efficient and scannable.

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 6 parameters (all aliases), no output schema, rich annotations, and 35 sibling tools, the description covers all essential aspects: purpose, when to use, when not to use, examples, internal behavior (routing), citation format, and tier compatibility. It even addresses edge cases like breaking news and steps up. No gaps remain for the agent to guess.

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 6 parameters (question plus 5 aliases) with 100% schema description coverage; each alias is described as 'Alias for question.' The description does not add parameter-level meaning beyond what the schema provides, but it does supply many usage examples (e.g., 'current US unemployment rate', 'Apple's latest 10-K'). Baseline is 3 given high coverage, and the description's examples are marginally helpful but not 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 explicitly states 'PREFER OVER WEB SEARCH' and enumerates a comprehensive list of data domains (SEC filings, FDA, FRED, etc.). It clearly explains that the tool routes questions to 5,564 tools across 1,462 sources and returns structured answers with citation URIs. This specificity and differentiation from siblings like deep_research and ask_pipeworx_grounded make the purpose exceptionally clear.

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

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

The description provides explicit when-to-use guidance: 'START HERE for most questions' and lists trigger phrases like 'what is', 'look up', 'find'. It also states when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions). This level of contextual instruction far exceeds typical tool descriptions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds context beyond these by revealing this is an experimental edge with candidate routing improvements, that results are compared to decide merges, and that the last candidate was retired. It does not contradict annotations (since it is a router, not a mutation). A slight deduction for not elaborating on potential side-effects of the experimental routing, but overall strong 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 a single paragraph of three efficient sentences. It front-loads the core identity ('Beta version of ask_pipeworx') and quickly covers scope, current state, and usage. Every sentence earns its place with no wasted words.

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

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

Given the tool's complexity (a router wrapping 5,564 tools) and the presence of rich annotations confirming safety (readOnly, idempotent) and open-world semantics, the description is complete enough. It explains the beta nature, what happens with candidates, and how it relates to the stable sibling. No output schema exists, but the description mentions the response shape is identical to the stable version, which is adequate since the stable router likely documents it. Minor deduction for not specifying return behavior when a candidate is active.

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%—the schema itself documents the 'question' field and all aliases thoroughly. The description does not add further parameter semantics beyond restating the schema information. Baseline 3 is appropriate as the description adds no additional meaning, but the schema already does the job.

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

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

The description clearly states it is a 'Beta version of ask_pipeworx: identical universal router' with the same tools, arguments, and response shape. It distinguishes itself from the stable sibling 'ask_pipeworx' by explaining it has candidate routing improvements under test, making the purpose specific and differentiating.

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

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

The description gives explicit guidance: use it 'when you want the newest routing' and notes 'Falls back to nothing — this IS a full working router'. It compares to the stable sibling by stating results are compared against the stable router, and clarifies that no candidate is currently active, so it currently matches the stable version. This provides clear when-to-use context without needing exclusions.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's main job is to add context. It does this well by explaining the refusal mechanism, the evidence extraction (verbatim quote), and the cost implication. However, it doesn't clarify what happens with partial matches or how 'not_in_source' differs from 'no_tool_match' in practice, which would be helpful for an agent.

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

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

The description is front-loaded with the key concept ('Hallucination-resistant answer mode'), then explains the mechanism, then the return format, then usage guidance. It's efficient but the return format details could be slightly more concise without losing value. The sentence about costs and preferring the alternative is valuable.

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 parameter simplicity (only 1 effective parameter), no output schema, and rich annotations, the description covers the needed ground well: it explains the behavior, the refusal reasons, the evidence format, and when to use/not use. The only gap is not explaining the routing mechanism in more detail, but the agent can infer from the sibling tool names.

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% (all 6 parameters are aliases for the same question field), so the description need not add much. It notes that the parameter accepts 'query, q, prompt, text, input as aliases', which is already in the schema. No additional semantics are added beyond what the schema provides.

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 'hallucination-resistant answer mode for high-stakes reads' with a specific verb+resource ('Extracts answer using ONLY what the tool result contains'). It distinguishes itself from sibling ask_pipeworx by noting the extra LLM call cost and the grounded refusal behavior.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples like financial verdicts, legal claims, medical lookups, public statements. Also explicitly says when to prefer the alternative: 'prefer ask_pipeworx for casual lookups' and explains the cost trade-off.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description goes far beyond by detailing the resolution process, fan-out behavior, response shapes (market, analysis, evidence), resolver contract, safety checks (low confidence, closed markets, wide spreads), and resolution-rule risk. No contradictions with annotations.

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

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

The description is very long with multiple paragraphs and exhaustive examples. While it front-loads the primary purpose, the abundance of detail may hinder quick parsing. Some redundancy exists, making it less concise than optimal.

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

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

Given the complexity (fan-out to multiple sources, safety checks, response shapes), the description covers all necessary aspects: input formats, classification, fan-out logic, response structure, error states, and rule risks. No output schema exists, so the description appropriately details return values and edge cases.

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

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

Schema coverage is 100% with clear descriptions for each parameter (market, depth, include_raw). The tool description adds extra context, e.g., default depth value, recommendation for include_raw, and examples. This adds value beyond the schema alone.

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

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

The description clearly specifies the tool researches a Polymarket bet by pulling Pipeworx data, with examples of accepted inputs (slug, URL, question text). It distinguishes itself from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on single-bet research with evidence packing and market-vs-model comparison.

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

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

Explicit use cases are given: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It provides classifiers and fan-out examples but does not explicitly contrast with sibling tools or state when not to use it. Still, the context is clear and actionable.

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

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

Description adds significant value beyond annotations by detailing exactly what data is pulled for companies (10-K revenue, net income, etc.) and drugs (FAERS counts, FDA counts). Mentions sorting by primary metric and citation URIs. No contradiction with annotations.

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

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

Single paragraph packs a lot of information efficiently, front-loaded with trigger phrases. Could be slightly more structured, but no unnecessary sentences. Earns 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?

Covers both entity types, key metrics, sorting, and return format (paired data + citations). No output schema but description compensates. Minor omission of limitations or error handling, but overall complete for a tool with annotations.

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

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

Schema coverage is 100%. Description clarifies the meaning of 'type' enum with data source details and provides concrete examples for 'values' (tickers/CIKs, drug names), enhancing understanding beyond the schema.

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

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

The description uses specific verbs like 'compare', 'rank', and 'head to head', clearly stating it performs side-by-side comparisons of 2-5 companies or drugs. It distinguishes itself from sibling tools by noting it replaces 8-15 sequential lookups.

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

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

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides example queries and details on data sources for each type. Lacks explicit when-not-to-use but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false, but the description adds substantial behavioral context: it explains parallel execution across tools, gap recovery in standard/thorough modes, return of explicit gaps[], contradictions[], hop fields, citation_uri (always fetchable), and large-record excerpting. This fully informs the agent about behavior beyond annotations.

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

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

The description is thorough and informative, but it is long and slightly rambling, mixing high-level mechanics (parallel tools) with fine details (excerpting technique) and a sales pitch (asking to sign up). Every sentence adds value, but front-loading could be stronger and some minor repetition exists (e.g., multiple mentions of gaps and contradictions).

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 (parallel tool invocation, multiple depth modes, gap recovery, contradictions, citation stability) and that there is no output schema, the description covers all critical aspects: expected latency, return structure, faillure mode (empty gaps[]), and account tiers. It fully compensates for the lack of an output schema and the tool's sophistication.

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

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

Schema coverage is 100% and the description adds nuanced meaning: for the 'depth' parameter it explains the number of facets and hops for each enum value (quick=3 single hop, standard=3 with gap recovery, thorough=6 paid with iterative chasing). For 'question', it clarifies that broad/multi-part is fine. This adds significant value beyond enum labels and descriptions 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 clearly states the tool performs 'grounded multi-source research' across a specific set of structured data sources, distinguishing it from open-web search. It explicitly contrasts with sibling ask_pipeworx by specifying use cases like broad/multi-part questions, single lookups, and breaking news, 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?

Provides explicit guidance on when to use this tool (broad/multi-part questions over structured data) versus when to use ask_pipeworx (single lookup, breaking news/colloquial topics). Also includes account requirements and sign-up instructions, as well as what to expect for different depth levels, giving agents clear decision criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by stating it 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This provides behavioral context beyond the annotations.

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

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

The description is a single paragraph but efficiently packs essential information: purpose, use cases, return type, and guidance to call first. It is front-loaded with the core action. Could be slightly more concise, but no unnecessary words.

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

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

Given the tool's complexity (many siblings, no output schema), the description adequately explains what the tool returns ('top-N most relevant tools with names, descriptions, and full input schemas') and why it's useful ('ready to call directly'). It does not cover ordering or pagination details, but the core usage is clear.

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

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

Schema description coverage is 100%, so the schema fully documents all 6 parameters. The description adds meaning by clarifying that the query parameter accepts natural language and noting aliases (task, q, description, search). This reinforces usage beyond the schema's individual descriptions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides explicit examples of domains (SEC filings, FDA drugs, etc.) and distinguishes from siblings by stating 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This separates it from sibling tools like search_datasets or suggest_questions.

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 explicit usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' While it hints at when not to use (when you want a direct answer), it does not explicitly mention alternatives among the many siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it fans out across multiple sources, notes patent data soft-fails after May 2025, and mentions news fallback (GDELT→GNews). 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 front-loaded with example queries, but it's a single long paragraph with a run-on list of return fields. While every sentence is useful, it could be more structured (e.g., bullet points) for readability. Still, it's efficient given the complexity.

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

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

Given no output schema, the description adequately describes the return structure (cik, company_name, recent_filings with URIs, fundamentals sorted, patents limitation, news fallback, LEI). It covers edge cases (name not supported, patent sunset) and recommends alternative tools. Complete for a holistic profile tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining 'zero-padded CIK' example, reiterating that names are not supported, and noting the type parameter only supports 'company'. This exceeds the baseline of 3.

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

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

The description clearly states the tool produces a 'full cross-source profile of a US public company in ONE parallel call,' listing specific data sources (SEC, XBRL, USPTO, news, GLEIF) and what it returns. Example queries like 'tell me about Apple' distinguish it from siblings like 'compare_entities' or 'resolve_entity'.

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 chaining single-pack SEC/XBRL/news lookups' for holistic views, and advises using 'resolve_entity first if you only have a name.' Clarifies supported inputs (ticker or CIK) and unsupported (names).

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 destructiveHint=true and readOnlyHint=false. The description adds context about clearing stale or sensitive data, which goes beyond annotations. No contradictions.

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

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

Three concise sentences covering action, usage, and sibling pairing with no wasted words. Information is front-loaded in the first sentence.

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 1-parameter tool with comprehensive annotations, the description covers purpose, usage, and behavioral traits adequately. No output schema needed.

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

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

Schema coverage is 100% for the single 'key' parameter. The description does not add significant meaning beyond what the schema already provides ('Memory key to delete'). 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 'Delete a previously stored memory by key' with a specific verb (delete) and resource (memory). It clearly distinguishes from siblings 'remember' and 'recall' which are create and read operations respectively.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with 'remember and recall', providing 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?

Describes fetching the page, extracting title/description/key links, and emitting standard llms.txt markdown. Annotations already indicate readOnly, idempotent, non-destructive; description adds behavioral detail beyond annotations without contradiction.

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

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

Four sentences, front-loaded with core purpose, then functional details, then use cases. No redundant or irrelevant information.

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

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

Given no output schema, description fully explains output format and placement. Low parameter count and high schema coverage mean no gaps remain.

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

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

Schema covers both parameters with descriptions. The tool description adds little beyond schema (e.g., 'extracts title/description/key links' is not parameter-specific). With 100% schema coverage, 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?

Clearly states the tool generates a production-ready llms.txt file for any URL, specifying the output format and use cases like indexing client sites or auditing competitors. Differentiates from siblings like ai_visibility_check.

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

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

Explicitly lists three use cases (client indexing, personal project, competitor auditing) providing clear context for when to use. Lacks explicit when-not-to-use or alternatives, but the specificity still guides 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 already declare safe read-only behavior (readOnlyHint, idempotentHint). The description adds valuable context about what specific information is returned (fields, geometry type, count, capabilities), going 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?

A single sentence that efficiently front-loads the tool's purpose and output details. Every word adds value; no redundant or unclear phrasing.

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 information tool with one parameter and no output schema, the description covers the key outputs. However, it omits potential issues like invalid URLs or permission requirements, which would enhance completeness.

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

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

With 100% schema description coverage, the baseline is 3. The description mentions 'by url' but does not add new semantic details beyond the schema's explanation of the 'url' parameter, which is already 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 uses a specific verb 'Get', identifies the resource as 'ArcGIS Feature/Map Service layer's schema', and enumerates the exact outputs (fields, geometry type, count, capabilities). This clearly distinguishes it from sibling tools like 'query_layer' which focus on data retrieval.

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

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

The description implies usage for schema information but does not explicitly state when to use this tool over alternatives (e.g., 'query_layer' for data) or any prerequisites. The context is clear but lacks direct guidance on selection or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating safe read operation. The description adds value by specifying the returned fields and implying default filtering to active subscriptions. No contradictions with annotations.

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

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

Two sentences, front-loaded with the core purpose, no redundant information. Every sentence adds value.

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

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

Despite no output schema, the description details the return fields. It covers usage context, behavioral traits, and parameter hint. Complete for a simple list 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 single parameter (include_inactive) is fully described in the schema with 100% coverage. The description mentions 'active' default but adds no additional semantic beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states it lists the caller's active subscriptions and specifies the returned fields (id, type, params, created_at, last_fired_at, fire_count). It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing and reviewing existing subscriptions.

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

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

The description explicitly provides usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This helps the agent decide 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?

Annotations are all false and provide minimal context, so the description carries the burden. It adds valuable behavior: rate-limited to 5 per identifier per day, free/doesn't count against quota, returns a claim_token, team reads digests daily, and signal affects roadmap. This goes beyond the schema and annotations, though it doesn't mention account-based response differences or data retention.

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 the core purpose and use cases. Most sentences earn their place (rate limit, quota, token flow, daily digests). There is slight redundancy in the exclusion warning ('ONLY for tools served by this Pipeworx connection' followed by the different-server example), but overall it is 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?

Tool complexity is moderate (4 params, nested context) and there is no output schema. The description explains the return token behavior and covers key context: what to report, what not to report, follow-up, rate limits, and team review cadence. Minor gaps remain, such as what exactly happens if the user has an account versus filing without one.

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

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

Schema coverage is 100% with descriptions on all parameters, giving a baseline of 3. The description adds meaningful extra semantics: how to use claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed'), and message guidance ('don't paste the end-user's prompt'). This enriches 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?

Description states 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which is a specific verb+resource pairing. It clearly distinguishes this feedback tool from the sibling tools (none of which handle feedback). The three-category breakdown (bug, feature/data_gap, praise) sharpens the purpose.

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

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

Explicitly says 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: if the tool came from a different MCP server, file with that server. The claim_token follow-up instructions further clarify when to invoke the tool with that parameter.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context: data derived from CF analytics-engine, no PII, caching behavior (5min-1h depending on window).

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

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

Well-structured paragraph with bullet points. Front-loaded with main function. Slightly verbose but efficient overall.

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

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

No output schema, but description adequately explains output format (top tools, top packs, total call volume). Completeness is high for a simple read-only 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?

Only one parameter 'window' with enum and description in schema (100% coverage). Description adds value by explaining trade-offs: shorter windows surface what's hot, longer show steady-state demand.

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

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

Clearly states it returns top tools, top packs, and total call volume over a recent window. Distinguishes from siblings like 'discover_tools' by focusing on agent call activity.

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?

Lists three specific use cases (discovering hot data sources, confirming canonical tools, aligning use case). Does not explicitly state when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false. The description adds extensive behavioral context: the scan returns opportunities with gap_pp, suggested_trade, reasoning; explains partition filter and fill check logic; describes cross-event mode using Jaccard similarity to prevent unrelated pairings; and notes when trades should be avoided. This significantly enriches the agent's understanding beyond annotations.

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

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

The description is well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, etc.) and front-loaded with the core purpose. While slightly verbose, every sentence adds value, and the organization facilitates reading. Could be marginally more concise but remains effective.

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 the tool's complexity and lack of an output schema, the description thoroughly explains all aspects: the two modes, filter logic, fill check, output fields (opportunities, partition_check, fill_check), and even references a sibling tool for custom sizing. It provides a complete mental model for the agent to use the tool correctly.

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

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

Schema coverage is 100% with both parameters described. However, the description adds substantial meaning: provides concrete examples of valid inputs (slugs, URLs for event; seed questions for topic), explains the different modes triggered by each parameter, and details the algorithmic behavior (date-axis ordering, partition checks, cross-event scanning). This far exceeds the basic schema descriptions.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This specific verb+resource combination effectively distinguishes it from sibling tools like polymarket_edges, polymarket_edge_tracker, and polymarket_fill_risk by detailing the unique algorithmic approach.

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

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

The description provides explicit guidance on when to use each parameter: 'Call with NO args for a trending_scan... pass event for... or topic for...' It includes recommendations ('event recommended for a specific market') and explains when not to trade based on fill check results, offering comprehensive 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?

The description adds extensive behavioral context beyond the annotations (readOnlyHint, idempotentHint). It explains caching at the KV level for 1 hour, the response structure with diagnostics, the underlying model families (e.g., crypto_price, news_momentum, partition_overround), and the treatment of Fed bets. It also discloses that edge_pp_net is after slippage and includes a 24h move warning. No contradictions with annotations.

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

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

The description is detailed but well-structured, using sections and bullet-like points to explain model families, response segmentation, and parameter usage. It front-loads the core purpose. While somewhat lengthy, every sentence adds value given the tool's complexity. A slightly more concise format could improve readability, but it is appropriately sized for the 9-parameter, multi-segment tool.

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

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

Despite the tool's complexity (9 parameters, no output schema, nested structures in response), the description covers all critical aspects: how each parameter affects output, the response top-level structure (by_segment, fed_candidates, diagnostics), details of model families, and caching behavior. It even provides specific mathematical values (e.g., κ for tennis=1.02). The absence of an output schema is fully compensated by the thorough textual description.

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

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

Schema coverage is 100%, providing a baseline of 3. The description significantly enriches each parameter beyond the schema, explaining implications (e.g., min_kelly: 'Skips opportunities that are too small to bet sensibly'), providing default values, and offering contextual advice (e.g., slippage_pp: 'Polymarket has zero trading fees... but bid/ask + thin depth typically eats 20-50bp per trade'). This is well above baseline.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It distinguishes itself from siblings by explaining its specific model families and segments, and explicitly targets the 'what should I bet on today' use case. The verb 'scan' and resource 'Polymarket markets' combined with the specific output segments make the purpose highly precise.

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

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

The description provides strong guidance on when to use the tool—for discovering arbitrage and edge opportunities without paging through hundreds of markets. It details how to adjust knobs like min_liquidity and max_spread_pp to realize edges, and explains the filtering logic. However, it lacks explicit comparison to sibling tools like polymarket_arbitrage or polymarket_edge_tracker, leaving some ambiguity about when to prefer this specific tool over alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds rich behavioral details: it reads snapshots, provides time-series, trend, decay, expired opportunities, and data gaps. No contradictions.

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

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

The description is well-structured, front-loaded with the core question, and includes response fields and limits. It is verbose but every sentence adds value; minor conciseness improvement possible.

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

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

Given complexity, no output schema, but the description thoroughly explains the response (tracked, expired, snapshot_dates), parameters, and limitations (TTL, gaps). Complete for agent understanding.

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

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

Input schema covers both parameters with descriptions. The description adds context ('max 30', 'window family options') and explains how they affect output, adding value beyond the schema.

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

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

The description clearly states that the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering 'how long has this edge existed and is it shrinking?' It differentiates from siblings by focusing on time-series analysis, not just current edges.

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

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

The description gives context when to use (e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades') and mentions limits (60-day TTL). It does not explicitly state when not to use or name alternatives, but the context is clear.

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

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

Annotations already flag readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context: walks order-book ladder, returns verdict flags, warns that partial basket fills convert arb into unhedged directional position (the dominant loss mode). No contradictions.

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

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

The description is lengthy but well-structured with clear headings (SINGLE-MARKET, BASKET) and bullet lists of return fields. Every sentence adds necessary detail for a complex tool. Minor redundancy (e.g., repeated mention of default size) could be trimmed, but overall it earns 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 (two modes, multiple return fields, risk warnings) and no output schema, the description comprehensively explains all aspects: parameters, behavior, return values (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, etc.), and key risk scenarios. It leaves no critical gaps.

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

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

Schema description coverage is 100%, so baseline 3. The description adds extra meaning: e.g., for size_usd it explains 'max spend on buys, target proceeds on sells' for single-market and 'settlement notional — shares per leg' for baskets. It also clarifies side defaults per mode. This goes beyond mere schema repetition.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes single-market and basket modes with specific verbs and resources, and covers edge cases like partial fills and directional risk.

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

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

Explicitly advises 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' providing clear when-to-use context and warning against theoretical overround on thin books.

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

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

The description extensively details behavioral traits: response contains leg-by-leg prices, matched spreads, compatibility_warning fields, temporal_alignment, and counters for skipped comparisons. It explains when spreads are meaningful vs not. Annotations already declare readOnly, idempotent, and non-destructive, and description adds context 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 the main purpose and uses clear sectioning (TWO MODES, RESPONSE, SAFETY FIELDS). It is somewhat verbose but every sentence adds value, and the length is justified by the complexity of the tool.

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

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

Given the tool's complexity and lack of output schema, the description fully covers return values (leg prices, spreads, compatibility_warning, temporal_alignment, counters) and edge cases (non-equivalent bet shapes, unrelated events, temporal misalignment). It leaves no significant gaps for an agent to understand how to use the tool and interpret results.

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

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

Schema coverage is 100% and description adds significant meaning: it explains the two modes, the list of topic shortcuts, and that explicit parameters override topic mapping. It provides examples (e.g., 'fed', 'btc') and clarifies the override behavior.

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

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

The description clearly states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It uses specific verbs and resource (spread) and distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison rather than within-venue arbitrage.

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

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

The description explains two modes (topic shortcuts and explicit pairing) and warns that most pre-mapped topics return compatibility warnings, implying when the tool may not be useful. It lacks explicit comparison to alternatives but context suggests this is the only cross-venue spread tool among siblings.

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

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

With annotations already declaring read-only, idempotent, and non-destructive behavior, the description adds that it returns attribute rows and geometry, and describes SQL-like filtering. No contradictions.

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

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

Two sentences: first explains function and key parameters, second gives a practical usage tip. No redundant information, front-loaded with the most important 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 no output schema, the description mentions return types (attribute rows, geometry) and explains sampling. It is complete for a query tool with strong annotations and schema coverage.

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

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

Schema covers all 6 parameters at 100%. The description adds value summarizing them as 'SQL-like where, comma-separated out_fields, order_by, limit, offset' and provides a concrete usage tip, exceeding 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?

Clearly states the action ('Query') and resource ('ArcGIS Feature Service / Map Service layer') and ties it to search_datasets. The distinction from sibling tools like search_datasets is implied by referencing its output.

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

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

Provides explicit guidance on how to use parameters, e.g., 'Use where="1=1" + out_fields="*" to sample.' It does not explicitly exclude alternative tools, but the examples and parameter descriptions give clear 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?

Description adds scoping by identifier and dual behavior (get/list) beyond annotations' readOnlyHint and idempotentHint. No contradictions.

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

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

Three sentences, front-loaded with core action, then examples and scoping. 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 1-param tool without output schema, description covers purpose, usage, and scoping. Could mention return format but overall adequate.

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

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

Schema coverage is 100% with parameter description; tool description adds context—key is saved via remember, omit to list all—enhancing 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?

Clearly states it retrieves a value by key or lists all keys, with specific examples. Distinguishes from siblings remember (save) and forget (delete).

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 (look up stored context) and pairs with remember/forget. Provides scoping context for agent decisions.

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

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

Description adds context beyond annotations: explains what each alert carries (source, citation_uri, payload), clarifies that setting mark_read affects next call, and mentions the same feed at a URL. No contradiction with annotations.

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

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

Description is concise (under 100 words) and front-loaded with the main purpose. However, it includes some redundant phrasing ('Polls work fine' could be inferred) but overall well-structured.

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

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

Given no output schema, description sufficiently covers return format and parameter usage. It explains what the tool does, what it returns, and how to use filters and mark_read. Missing pagination details but schema covers limit.

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

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

Schema coverage is 100%, so baseline is 3. Description adds minimal extras (e.g., type example 'sec_8k', polling info) but mostly paraphrases schema. Does not significantly enhance understanding beyond schema.

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

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

The description clearly states 'Pull fired events from your subscription feed', specifying the verb (pull) and resource (fired events). It distinguishes from sibling tools like 'list_subscriptions' and 'subscribe' by focusing on retrieving alerts rather than managing 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?

Provides explicit usage context: filter by type and since, set mark_read, notes polling works fine, and mentions an alternative GET endpoint. While it doesn't contrast with all siblings, it gives enough guidance for the main use case.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds valuable behavioral context: parallel call structure, GDELT→GNews fallback, USPTO soft-fail, and return format (changes[], total_changes, citation URIs). No contradictions.

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

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

Description is a single dense paragraph but well-organized: starts with example queries, then sources, parameter details, return type, and sibling comparison. No wasted words, but could benefit from minor structural improvements (e.g., bulleted list).

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

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

No output schema, but description clearly explains return structure (changes[] grouped by source, total_changes, citation URIs). Covers fallback behavior (GDELT→GNews), USPTO status, and source limitations. Complete for a change-feed tool of moderate complexity.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. Description adds value by explaining since parameter syntax (ISO date or relative shorthand) and recommending a typical value ('30d' or '1m'). Provides more context than schema alone.

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

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

Description starts with clear example queries, explicitly states it is a 'change feed for a company in the last N days/weeks/months in ONE parallel call,' lists data sources (SEC, GDELT/GNews, USPTO), and distinguishes from sibling tool entity_profile. Highly specific 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?

Provides explicit 'when to use' via example queries and recommends using entity_profile for static profiles. Includes detailed parameter guidance (since accepts ISO dates or relative shorthand) and recommended default ('30d' or '1m'). Clearly distinguishes from alternatives.

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

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

Annotations already declare idempotentHint true and destructiveHint false. The description adds useful behavioral details: scoping by identifier, 24-hour retention for anonymous sessions, and persistent memory for authenticated users.

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

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

Four sentences, each serving a purpose: core action, use case, scoping/persistence, companion tools. No fluff, front-loaded with primary purpose.

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

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

For a simple two-parameter tool with no output schema, the description covers all necessary context: what it does, when to use, scoping, persistence, and related tools. Nothing missing.

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

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

Schema covers both parameters with descriptions. The description enriches with concrete examples for key ('subject_property') and value ('findings, addresses'), adding meaning beyond schema.

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

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

The description clearly states the tool's purpose: to save data for reuse later. It provides specific examples of what to store (ticker, address, preference) and distinguishes itself from siblings by mentioning recall 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?

Explicitly states when to use ('when you discover something worth carrying forward') and provides examples. It also mentions companion tools (recall, forget) for retrieval and deletion, guiding the agent on alternatives.

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

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

Annotations already indicate readOnly, idempotent, openWorld, and non-destructive behavior. The description adds significant behavioral context: it cascades through multiple lookup endpoints internally, degrades gracefully (EDGAR identifiers return even if GLEIF/OpenFIGI are unavailable), and explicitly states that unresolved identifiers are listed under 'unresolved' rather than omitted. This goes well beyond what annotations provide.

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

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

The description is front-loaded with clear examples and usage guidance, making the purpose immediately apparent. However, it is quite verbose (about 150 words) with detailed explanations of each identifier source and fallback behavior. While every sentence adds value, the description could be slightly more concise without losing clarity. It is well-structured but not maximally efficient.

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

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

Without an output schema, the description must explain return values, and it does so thoroughly. For 'company', it describes the identifiers from SEC EDGAR, GLEIF, and OpenFIGI, including ownership hierarchy and unresolved identifiers. For 'drug', it covers RxCUI, ingredient, brand, and citation. It also addresses edge cases like ISIN resolution and graceful degradation. The description is complete for a tool with two parameters and no output schema.

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

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

The input schema has 100% description coverage, with both 'type' and 'value' described. The description adds substantial meaning beyond the schema: for 'company', it explains the rich set of identifiers returned (CIK, ticker, LEI, FIGI, etc.) and their sources; for 'drug', it specifies RxCUI, ingredient, brand, and citation. It also clarifies that 'value' can be ticker, CIK, ISIN, or company name, which the schema only hints at.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with specific examples like 'What's the ticker for…' and 'find the CIK for…'. It distinguishes itself from sibling tools by explicitly saying 'Use FIRST whenever you have a name but need an ID', making its role as the initial lookup tool unambiguous.

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

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

The description provides explicit guidance on when to use the tool: 'Use FIRST whenever you have a name but need an ID'. It also gives concrete examples of queries that trigger this tool. While it doesn't explicitly list when not to use it, the directive 'Use FIRST' implies it is the starting point before other tools like entity_profile, which is sufficient for an AI agent.

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

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

Describes probing each entity with ai_visibility_check, ranking, and returning ranked list with score, confidence, signal density. Adds behavioral detail beyond annotations which only state readOnly, idempotent, non-destructive.

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: purpose, method, example. Front-loaded and efficient with no filler. Every sentence adds value.

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

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

No output schema, but description clearly states return value (ranked list with score, confidence, signal density). Covers behavior and parameters adequately for a complex tool.

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

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

Schema covers all parameters with descriptions (100%). Description adds key nuances: first entry treated as 'subject', models can be omitted for default, context disambiguates. This extra context is valuable beyond schema.

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

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

Clearly states 'Compare AI visibility across multiple entities side-by-side.' Specific verb 'compare' and resource 'AI visibility'. Distinguishes from sibling ai_visibility_check (single probe) and compare_entities (generic comparison).

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

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

Indicates usage for 'competitive AI-marketing audits' and gives an example. Implicitly excludes single-entity checks (use ai_visibility_check). Does not explicitly list alternatives but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list if it times out. No contradiction.

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

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

Description is longer but well-structured and front-loaded. Every sentence adds value; it explains purpose, sources, return structure, and failure behavior. Could be slightly more concise without losing clarity.

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

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

Given the tool's complexity (composite, multiple sources, partial failures), the description is thorough: covers return fields, sources, failure behavior, ecosystem scope, and usage context. No output schema needed as description adequately details 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%, baseline 3. Description adds context: 'Scoped packages are accepted' and 'Defaults to the latest published version when omitted.' This goes beyond schema.

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

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

Clearly states it's a composite check for npm package evaluation covering license, advisories, version history, and bundle size. Distinguishes from siblings by specifying NPM ecosystem only and directing other ecosystems to deps.dev:version directly.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". Also notes NPM ecosystem only and mentions alternatives for other ecosystems.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the tool is clearly non-destructive. The description adds beyond that by detailing the return structure (name, summary, record_count, owner/org, url) and the recommended follow-up usage, providing useful behavioral context for an agent.

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

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

Single, well-structured sentence that front-loads the action and scope, includes key details about returns and chaining, and avoids fluff. Every part adds value.

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

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

For a search tool with 3 parameters, no output schema, and rich annotations, the description fully captures purpose, return fields, and integration with siblings. Nothing essential is missing for an 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?

Schema coverage is 100% with adequate descriptions for all three parameters (limit, query, org_id). The description does not add details about the parameters beyond listing examples in the schema; it focuses on the output. Baseline 3 is appropriate as 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 uses precise verbs ('Search') and specifies the resource ('St. Louis County GIS open geospatial datasets') and scope ('by keyword'). It lists exact return fields and mentions how the output URL can be used with sibling tools (query_layer, layer_info), distinguishing it from those tools.

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

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

The description implicitly states when to use the tool (when searching for datasets) and provides explicit guidance on how to chain it with query_layer/layer_info using the returned url. However, it does not explicitly describe when not to use it or compare it to other search-related siblings like search_within.

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

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

Annotations declare readOnly, openWorld, idempotent, not destructive. The description adds rich behavioral details: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char limit with truncation flag. This goes well beyond the annotations and sets clear expectations.

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 long, each adding distinct value. The core action is front-loaded in the first sentence. While not ultra-compact, it avoids verbosity and maintains clarity.

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

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

Given no output schema, the description explains the return format (top-N passages with offsets and scores). It also mentions the 200K char limit and ties to a sibling tool. Could elaborate on interpreting similarity scores, but overall covers key usage aspects.

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

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

Schema coverage is 100% with parameter descriptions. The description enriches each: for 'text' specifies max chars, for 'query' gives natural-language examples, for 'limit' provides range and default. This adds meaning beyond the schema alone.

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

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

The description clearly states it performs 'semantic search INSIDE a fetched record', gives concrete examples (SEC 10-K, article), and distinguishes from external search by focusing on content already retrieved. The verb 'search' and resource 'within a source' are specific 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?

The description explicitly advises using this tool 'when the record is too big to cram into the prompt' and contrasts it with 'ask_pipeworx_grounded' for a pairing strategy. While it could mention more alternatives, the guidance is clear and actionable.

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

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

Annotations already indicate mutation, open world, idempotent, non-destructive. Description adds context about authentication requirements, return of subscription ID, and detailed delivery behaviors (webhook signing, auto-disable). No contradictions.

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

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

The description is informative and well-structured, front-loading the purpose. It is somewhat lengthy but every sentence adds value. Minor room for trimming but overall efficient.

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

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

For a complex tool with nested objects and multiple types, the description covers prerequisites, examples, limitations, and return value thoroughly. No output schema but return value is mentioned. Complete for the given complexity.

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

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

Schema coverage is 100%, but description adds significant meaning with concrete examples for each type, delivery channel details, and edge-case behaviors, going well beyond the schema descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream, with a specific verb and resource. It distinguishes from siblings 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?

Provides explicit prerequisites (Pipeworx OAuth account) and limitations (SMS verification, rate caps). Does not explicitly define when not to use, but examples and sibling context make usage clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context beyond annotations by explaining that the tool returns example questions (not actual data) and describes the output structure (category-bucketed with tool+argument shapes). It does not contradict annotations.

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

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

The description is relatively long but well-structured. It front-loads common user queries, then explains the output, parameter usage, and when to use. Every sentence adds value, though some repetition (e.g. listing categories twice) could be trimmed slightly. Overall efficient for the information conveyed.

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

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

Despite no output schema, the description fully explains what the tool returns (category-bucketed example questions with tool calls). It covers parameter behavior, use cases, and relationship to other tools. For a tool with one optional parameter, this is complete and leaves no ambiguity.

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

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

Schema coverage is 100%, and the description adds meaningful usage context for the single optional 'topic' parameter: it lists valid focus areas ('finance | pharma | economics...') and explains that omitting it yields a cross-category spread. This is valuable guidance beyond the schema's type description.

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

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

The description clearly states the tool's purpose as an onboarding entry point for discovering Pipeworx capabilities. It lists explicit user intents ('What can I ask?', 'give me ideas', etc.) and specifies the output: category-bucketed example questions with tool+argument shapes. It distinguishes itself from sibling tools by being the first tool to use when the agent doesn't know what Pipeworx can do.

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

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

Provides explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also mentions alternatives like ask_pipeworx, entity_profile, compare_entities. This clearly tells the agent when and when not to use this tool.

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

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

The description adds behavioral context beyond the annotations: it reveals that rows are deactivated (not deleted) and that historical events remain accessible via recent_alerts. This is valuable information not captured by readOnlyHint, destructiveHint, or idempotentHint.

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) with no redundant words. It front-loads the action and immediately provides key constraints (ownership and deactivation behavior). Every sentence 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 tool with one parameter and no output schema, the description fully covers the purpose, behavioral effect (deactivation), ownership rules, and impact on historical data. No gaps remain given the tool's complexity.

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

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

The input schema already describes the parameter 'id' as a UUID returned by subscribe, and the description reaffirms this. With 100% schema description coverage, the baseline is 3; the description adds no new semantic details beyond reinforcing the schema.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource ('subscription'). It distinguishes from its sibling 'subscribe' by implying the opposite operation. The verb 'cancel' is specific 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?

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions'), providing clear usage constraints. While it does not mention when not to use or suggest an alternative tool, the given context is sufficient for the 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?

Beyond the readOnly/openWorld/idempotent annotations, the description adds critical behavioral detail: the distinction between could_not_verify (check did not happen, not evidence) and unsupported (no source found), plus the return of verbatim evidence with a pipeworx:// citation. It also exposes the routing decision (fast path vs. grounded pipeline), giving the agent actionable understanding of failure modes.

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 long, every sentence earns its place: examples, routing logic, return contract, and critical caller warnings. The structure flows from purpose to behavior to edge cases, and no content is redundant with the schema or annotations.

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 specifies the return contract (verdict set, actual value with citation, reasoning) and explains the semantic difference between could_not_verify and unsupported. It covers both parameters and the routing, making the tool self-contained and safe to invoke.

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

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

Schema coverage is 100% so baseline is 3. The description adds extra semantics for tolerance_pct by explaining it overrides the claim's implied tolerance, recommending 1–2% for hallucination detection, and noting the default is capped at 5%. This goes beyond the schema's brief description, so a 4 is warranted.

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 natural-language phrasings ('Is it true that…', 'fact check', 'verify the claim that…') and states the core function: natural-language claim verification against authoritative sources. It clearly differentiates from siblings by describing a two-path routing architecture (SEC EDGAR/XBRL for company-financial claims, grounded pipeline for all else) and notes it replaces 4–6 sequential calls, making its unique 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?

The description gives an explicit trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the fallback behavior for any non-financial claim. However, it does not name alternative tools or explicitly state when not to use this tool, though the phrase 'replaces 4–6 sequential calls' implies it is the canonical path.

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