Arcgis Charlotte

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

Annotations already provide read-only, open-world, idempotent, and non-destructive hints. The description adds valuable behavioral context: default model selection, cost implications (BYO key, direct payment to Anthropic), and external API calls. It does not contradict annotations and supplies extra operational detail beyond the structured metadata.

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

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

The description is three sentences, each earning its place: core function and output, configuration/cost details, and use cases. It is front-loaded with the primary purpose, contains no fluff, and is efficient for an agent to parse.

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

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

With no output schema, the description compensates by explicitly listing the return structure (per-model score, confidence, signals, raw_response, combined view). It covers default behavior, configuration, and use cases. It stops short of addressing error handling, rate limits, or what 'signals' means, but those are secondary for this tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches `models` and `_apiKey` by explaining the default free model and the cost/bring-your-own-key behavior, which is not fully captured in the schema. It does not add specific meaning to `context`, but the schema already handles that well.

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

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

The description clearly states a specific action ('Probe one or more LLMs') and the resource (business/brand/product/topic) with a defined output (visibility score 0-100). It distinguishes itself from sibling tools like ask_pipeworx (which likely answers questions) and scan_competitor_ai_presence (which is competitor-focused) by emphasizing generic entity visibility scoring.

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

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

It lists concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') making it easy to judge when to apply. However, it does not explicitly advise when NOT to use it or contrast with alternatives, leaving a small gap.

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, openWorldHint=true, and destructiveHint=false. The description adds behavioral context beyond annotations: routing across many tools, filling arguments, returning structured answers with citation URIs, and works on every tier. It does not contradict annotations, and the added context is useful.

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

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

The description is substantial but every sentence earns its place: it covers preference over web search, routing behavior, alternative tools, trigger phrases, examples, and default status. It is front-loaded with the most critical guidance ('PREFER OVER WEB SEARCH') and remains well-structured 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 the tool's complexity (routing across 5,529 tools) and no output schema, the description is remarkably complete. It covers purpose, usage, alternatives, examples, and even mentions 'one fast call' and 'works on every tier'. While it doesn't describe a formal return schema, it explicitly mentions 'structured answer with stable pipeworx:// citation URIs', which is sufficient for an agent to know what to expect.

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 full coverage (100%) with the question parameter description already explaining aliases. The tool description adds semantic value by specifying the types of questions ('current or historical data... factual question about real-world entities') and providing concrete examples ('current US unemployment rate', 'Apple's latest 10-K'), which helps agents formulate the 'question' parameter more effectively.

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

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

The description uses specific verbs and resources: 'Routes the question to the right one of 5,529 tools across 1455 verified sources... returns the structured answer with stable pipeworx:// citation URIs.' It also clearly distinguishes from siblings by naming alternatives like ask_pipeworx_grounded and deep_research, making the purpose unmistakable.

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

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

Explicitly states when to use this tool over alternatives: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and provides conditional guidance: 'Step up only when needed: for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.' Also gives trigger phrases and examples.

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 convey read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it's a live experimental router with candidate routing improvements, currently equivalent to ask_pipeworx, and results are compared against the stable router. It also clarifies it's a full working router, not a fallback. This goes beyond annotations.

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

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

The description is a bit long but each sentence provides necessary context about the beta status, current equivalence, usage, and purpose. It is front-loaded with the key point (beta version of ask_pipeworx) and remains structured, though slightly verbose.

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

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

For a tool with no output schema and complex experimental behavior, the description covers the essential context: what it does, current state, how to use it, and how it relates to the stable version. It mentions 'same response shape' but doesn't elaborate; however, given the sibling ask_pipeworx, this is adequate.

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

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

Schema coverage is 100% with clear parameter descriptions for 'question' and aliases. The description doesn't add parameter details, but it says 'same arguments' as ask_pipeworx. Since the schema already covers all parameters, the baseline of 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx with a specific role: a universal router with candidate routing improvements. It distinguishes from siblings by calling out the experimental edge and explicitly comparing to the stable ask_pipeworx. The verb 'use' and resource 'ask_pipeworx beta' are 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?

Explicit guidance is given: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the current equivalence to ask_pipeworx when no candidate is active. It doesn't explicitly say when not to use it, but the context implies it's for experimental purposes while stable ask_pipeworx is available.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses key behaviors: it extracts answers only from tool results, returns structured success/refusal objects, enumerates all refusal reasons, and notes the extra LLM call cost. This significantly supplements the annotation data.

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

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

The description is long but densely informative, with no filler. It front-loads the core purpose and then covers return format, usage, and cost. The exact source counts (5,529, 1455) add specificity but could be trimmed; nevertheless, the structure is clear and logical.

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 fully explains return values and refusal reasons. It also provides usage context, comparison with the sibling tool, and cost implications. This is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% and all parameters are aliases for a single natural-language 'question.' The description adds no extra parameter-level detail, but the schema already fully documents them. This matches the baseline for high coverage.

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

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

The description clearly identifies this as a 'hallucination-resistant answer mode' and distinguishes it from the sibling ask_pipeworx by stating 'Same routing as ask_pipeworx' but adding grounded extraction. It specifies the tool's precise role: answering with evidence and refusals when data doesn't directly answer.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on' and provides concrete examples (financial verdicts, legal claims, medical lookups). It also gives an exclusion: 'prefer ask_pipeworx for casual lookups,' naming the alternative and 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?

The description goes far beyond annotations by disclosing the resolver contract (market_match_confidence, alternatives), blocking low-confidence short-circuits, market_closed_or_inactive status, wide-spread illiquidity warnings, and cancellation-rule risk. It also details GDELT 429 fallbacks. This richness supplements the readOnly/openWorld 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?

Front-loaded with purpose and usage, then organized via CAPS-labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY). Each section adds unique value, but the overall length is substantial and could be trimmed for quick scanning.

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

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

Despite no output schema, the description defines result.market, result.analysis, result.evidence, parent_event, market_match fields, status values, and conditions for field suppression. It covers failure modes (GDELT 429s), safety (low-confidence blocking), and edge cases (cancellation rules). This is a complete picture for an agent to invoke and interpret the tool.

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

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

The input schema already covers all three parameters with clear descriptions (market input types, depth enum, include_raw size implications). The description adds fan-out examples but no new parameter-level semantics. Baseline 3 is appropriate for 100% schema coverage.

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

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

Description states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call', clearly identifying the verb, resource, and action. It specifies input forms (slug, URL, text) and output (evidence packet + market-vs-model comparison). The 'Use for' list differentiates it from general research tools like ask_pipeworx or deep_research.

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

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

Provides explicit use cases ('should I bet on X', 'what does the data say about Y') and a quick vs thorough depth option. However, it does not name alternative tools or state when not to use this tool, so it lacks explicit exclusions or alternatives.

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

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

Annotations already declare read-only/idempotent/non-destructive; description adds critical behavior: pulls SEC EDGAR/XBRL 10-K data, handles off-calendar fiscal years, sorts results by primary metric, returns paired data with pipeworx:// citation URIs. No contradiction.

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

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

Dense but efficient—starts with trigger phrases, then core function, then type-specific data, sorting, and return format. Every sentence adds new information; no redundancy or padding.

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 only 2 params and no output schema, the description fully covers input semantics, output structure (paired data + citation URIs), sorting behavior, data sources, and edge-case handling (off-calendar fiscal years). Sufficient for an agent to invoke correctly without further clarification.

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

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

Schema covers both parameters with 100% descriptions. Description adds value by detailing what each type selects (company→10-K financials, drug→FAERS/FDA/trial counts) and gives concrete examples (AAPL/MSFT, ozempic/mounjaro) plus sorting behavior. Minor gap: doesn't specify exact input formatting for drug names beyond examples.

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

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

Clear verb+resource: side-by-side comparison of 2–5 companies or drugs. Trigger phrases ("X vs Y", "rank these companies") anchor intent, and the explicit "ALWAYS PREFER over sequential single-pack lookups" distinguishes it from single-entity tools like entity_profile.

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

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

States exactly when to use: "ALWAYS PREFER over sequential single-pack lookups when comparing entities." Provides query examples and differentiates company vs drug type, plus what data each returns. Also notes it replaces 8–15 sequential lookups, guiding cost/latency 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes far beyond this by disclosing decomposition into facets, parallel routing to 5,529 tools, gaps[] that are never invented, depth-specific hop behavior, contradictions[] for standard/thorough, semantic excerpting, citation_uri resolvability, and expected latency. No contradiction with annotations is present.

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 (around 300 words) but front-loaded with the most critical info (account requirement, core purpose, alternatives). Every sentence adds meaningful detail—data sources, output structure, depth semantics, citation guarantees, latency. While not as terse as ideal, the density is justified by the tool's complexity. A 4 reflects good structure with minor verbosity.

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, the absence of an output schema, and minimal parameters, the description fully compensates by detailing the return packet (verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]), behavioral nuances (semantic excerpting, depth hops), and operational constraints (account, latency, alternatives). It leaves few open questions for an agent deciding to invoke this tool.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches the depth parameter by explaining the paid plan requirement, gap-recovery behavior, and additional leads chasing for thorough, which is not fully captured in the schema. It also adds examples and context for the question parameter. This exceeds the schema's basic descriptions, meriting a 4 but not a 5 since the schema already covers parameter basics.

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

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

The description opens with a specific verb+resource: "Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources" and clearly distinguishes itself with "this is NOT open-web search". It explicitly differentiates from sibling ask_pipeworx by contrasting broad/multi-part research versus single lookups and news topics, leaving no ambiguity about what this tool does.

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

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

Provides explicit when-to-use guidance with named alternatives: "Best for broad/multi-part questions over structured data", "For a single lookup use ask_pipeworx", "For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx". It also states account prerequisites and fallback behavior if not signed in, which is exactly the kind of situational guidance an agent needs.

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

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

The description discloses what the tool returns: '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 goes beyond the annotations (readOnlyHint, idempotentHint) and clarifies the tool's non-mutating discovery behavior. It doesn't explain relevance ranking but that's a minor gap.

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

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

The description is front-loaded with the core purpose, followed by usage context, return behavior, and a clear 'call first' instruction. The list of domains is lengthy but useful for disambiguation. No filler or redundant metadata; 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 as a discovery meta-tool and the absence of an output schema, the description is complete. It fully specifies the return format (names, descriptions, schemas), key behavior (relevance-ranked), and usage timing. The input schema covers parameters, so no critical information is 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 description coverage is 100%, so the schema already fully documents all 6 parameters, including the required 'query' and its aliases. The description adds no extra parameter insight beyond the schema, which is the baseline expectation for high coverage. The examples in the schema enrich the query parameter without needing description text.

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 uses a specific verb (find/discover) and resource (tools), and lists many domains it covers. This distinguishes it from the sibling tools which are domain-specific, while discover_tools is a meta-tool for browsing the whole toolset.

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: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear context and implies when not to use it (when you already know the exact tool), providing strong usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the bar is lower. The description adds valuable behavior beyond annotations: fan-out across SEC EDGAR, XBRL, USPTO, news, and GLEIF; a patent source that 'soft-fails until reactivated'; and a GDELT→GNews fallback chain. It also clarifies that the call runs in parallel.

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 dense single paragraph, but it is front-loaded with natural-language trigger examples and prioritizes key guidance ('ALWAYS PREFER'). Every sentence adds useful information—sources, return fields, and limitations—though it could be tightened with bullet-point formatting. Still, for a multi-source tool, the length is justified.

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

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

Without an output schema, the description fully compensates by enumerating return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and noting limitations (names unsupported, patent API sunset). It also situates the tool among siblings by naming resolve_entity and comparing against chained single-pack lookups, making it complete for an agent to select and invoke correctly.

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

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

The input schema already covers both parameters 100%, including the type enum and the value format with the same 'Names not supported — use resolve_entity first' note. The description mostly repeats this ('Pass ticker "AAPL" or zero-padded CIK "0000320193"'), adding no substantive meaning beyond the schema. The baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description opens with concrete user-phrase examples ('Tell me about X', 'research Acme') and then states 'full cross-source profile of a US public company in ONE parallel call.' It uses specific verbs and resource scope, and clearly distinguishes itself from sibling tools like compare_entities and deep_research by emphasizing single-tool holistic extraction and 'ALWAYS PREFER over chaining single-pack lookups.'

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

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

Explicit guidance is provided: use this when the user asks for a holistic view, and 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' It also gives an exclusion ('names not supported') and names the alternative tool to use first ('use resolve_entity first'), making when-not-to-use 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 destructiveHint=true and idempotentHint=true, so the bar is lower. The description adds value by explaining the rationale for deletion (stale context, sensitive data) and implies irreversibility by using 'delete.' It does not contradict annotations and provides useful behavioral context beyond the structured hints.

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 coherent sentences deliver all essential information. The first sentence states the action and scope, the second provides usage guidance and tool pairing. No filler words or redundant repetition of schema information.

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

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

For a single-parameter delete operation with full schema coverage and annotations, the description is complete. It explains what, when, and how to use, plus complementary tools. No output schema exists, but the return value is not critical for a destruction operation.

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

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

The schema covers the only parameter 'key' with a clear description ('Memory key to delete'), giving 100% coverage. The description reinforces the role of the key but adds no new parameter-level detail. Baseline 3 is appropriate since the schema handles the heavy lifting.

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

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

The description opens with a specific verb+resource: 'Delete a previously stored memory by key.' This clearly distinguishes the tool from siblings like remember and recall, which store and retrieve memories respectively. The addition of 'previously stored' and 'by key' scopes the operation precisely.

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

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

The description explicitly states when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also suggests complementary tools with 'Pair with remember and recall,' providing clear context for when this tool is appropriate 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 already indicate read-only, idempotent, non-destructive behavior. The description adds behavioral context by explaining the tool fetches the page, extracts key information, and emits a standard markdown output. It also states the output is a single text blob ready for deployment, which is useful 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 concise, front-loaded with the core purpose, and each sentence adds value: purpose, process/output, and use cases. No redundant information or fluff.

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

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

For a simple tool with only 2 parameters, full schema coverage, and good annotations, the description is complete. It covers what the tool does, how it works, what output to expect, and typical use cases, making it fully self-contained.

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

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

Schema description coverage is 100%, so both parameters (url and max_links) are already well-documented. The description adds minimal extra meaning beyond the schema, only hinting at the extraction process. This aligns with the baseline of 3 for high schema coverage.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with a specific verb ('Generate') and resource ('llms.txt file'). It also details the process (fetches page, extracts title/description/key links) and distinguishes this from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on file generation rather than analysis.

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

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

The description provides clear use cases ('getting a client's site indexed by AI', 'drafting llms.txt for your own project', 'auditing how an AI crawler would see a competitor'). However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, providing a safety profile. The description adds useful context by clarifying that the tool returns schema metadata (fields, geometry, count, capabilities) rather than data, which is a meaningful behavioral trait. No contradictions with annotations exist.

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

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

The description is a single, front-loaded sentence that efficiently lists the tool's purpose and outputs. Every word earns its place, with no redundancy or irrelevant detail.

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 one-parameter, read-only tool with no output schema, the description is quite complete: it specifies the input (URL), the operation (get schema), and the expected output contents. The lack of explicit usage guidance is a minor gap but is already covered under usage guidelines.

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

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

Schema description coverage is 100% with a clear description of the 'url' parameter. The description's mention of 'by url' aligns with the schema without adding new semantics. Baseline 3 applies 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 clearly states it retrieves an ArcGIS Feature/Map Service layer's schema by URL, listing specific outputs: fields (name + type), geometry type, total record count, and capabilities. This specific verb+resource combination distinguishes it from sibling tools like query_layer, which imply data retrieval rather than schema inspection.

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 by focusing on schema retrieval via URL, but it does not explicitly state when to use this tool vs alternatives such as query_layer. There is no mention of exclusions or when-not-to-use, so the guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds the 'caller's active subscriptions' scope clarification but no additional behavioral details beyond what annotations provide. It doesn't discuss pagination, ordering, or edge cases, which would add depth.

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, perfectly front-loaded with the verb and resource, followed by return fields and a use-case hint. Every word earns its place, with no redundancy.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers the key elements: what it returns, scope, and when to use it. It doesn't mention error conditions or response format beyond fields, but this is adequate for the tool's simplicity.

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

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

The schema fully documents the single optional include_inactive parameter with a clear description. The tool description adds no extra parameter-level detail, so it relies on schema coverage, which is sufficient at 100%.

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

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

The description clearly states the tool lists the caller's active subscriptions, a specific verb and resource, and enumerates the returned fields. It distinctly differentiates from sibling tools like subscribe and unsubscribe by framing this as a review step before adding or canceling.

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

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

Provides explicit use cases: 'review what you're monitoring before adding more' and 'to find an id to cancel.' While it doesn't name subscribe/unsubscribe as alternatives, the context strongly implies when to use this tool versus when to use siblings, giving clear practical guidance.

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

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

Annotations are minimal (all hints false) and don't reveal the behavioral traits disclosed here. The description adds valuable context: the tool returns a claim_token when filing without an account, supports later lookup with that token, is rate-limited to 5 per identifier per day, is free, and doesn't count against quota. It also warns not to paste end-user prompts, which is a behavioral constraint 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 longer than average but every sentence earns its place: it covers what, when, exclusions, claim_token behavior, rate limit, and quota exemption. It is front-loaded with the primary purpose and then layers details logically. No redundant or filler sentences.

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

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

Given there is no output schema, the description adequately explains the return behavior (claim_token on filing, later status/change lookup) and the feedback workflow. It also provides operational context (daily reads, roadmap impact, rate limit, no quota) that an agent needs to decide whether to invoke the tool and what to expect. For a feedback tool with several behavioral nuances, the description is complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining when to use each feedback type (e.g., 'bug = something broke or returned wrong data') and by illustrating the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'). It also adds the practical constraint on message content ('don't paste the end-user's prompt'). This raises it above baseline, though much of the schema's own descriptions are already detailed.

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

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

The description opens with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly enumerates the feedback categories (bug, feature/data_gap, praise), and this tool is clearly distinct from siblings, which are research/query tools. The scope is precisely bounded to Pipeworx connection 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 gives explicit when-to-use guidance: '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 critical exclusion: if the tool is from another MCP server, file with that server instead, and tells how to disambiguate ('Pipeworx tool names are the ones this connection lists').

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 read-only, open-world, and idempotent hints. The description adds meaningful context: data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). It does not detail return structure, but the description's additional detail goes beyond annotations without contradiction.

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

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

The description is well-structured: core function first, then actionable use cases, then technical notes. Every sentence adds value, and the length is appropriate for the tool's simplicity.

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

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

For a simple one-parameter read-only tool with strong annotations and full schema coverage, the description is complete. It covers purpose, use cases, data source, privacy, caching, and the nature of the returned data, making it sufficient for an agent to decide when and how to use it.

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

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

The schema covers the only parameter 'window' completely, including enum values and a description of effect. The tool description merely mentions the window options and adds no extra semantic detail beyond what the schema already explains, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume' over a time window. It distinguishes itself from siblings by focusing on aggregate trending data from other AI agents, not individual actions or queries.

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 concrete use cases, such as discovering hot data sources and validating canonical choices before asking questions. It provides clear context but does not explicitly name alternatives or exclusion criteria, though the use cases imply when it is appropriate.

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?

Even though annotations already declare readOnlyHint, openWorldHint, and destructiveHint=false, the description adds substantial behavioral detail: it explains FILL CHECK behavior (realizable_edge_pp ≤ 0 means overround only at last-trade, 'do not trade it'), Jaccard similarity filtering, placeholder filtering returning null signals, and exposes 'skipped_low_similarity' as output. This context significantly expands what the agent knows about the tool's 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 long and dense with technical detail, but it's well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. While every sentence provides useful information, the extreme length and technical jargon could have been trimmed or split into separate documentation 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 and the absence of an output schema, the description fully specifies the return shape (opportunities[], partition_check, fill check metrics), edge cases (null arb signal, thin_legs), and references to related tools for complementary functionality. The combination of annotations and description leaves no major gap for an agent to invoke 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 description coverage is 100%, but the description provides deep semantic guidance: it defines each parameter's use case, gives concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), and clarifies the no-args default (trending_scan). It also explains how event vs topic modes differ and what output to expect, adding far more value than the schema's short descriptions.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (trending_scan, event, topic) and names the exact approach, making it easy to understand what the tool does and how it differs from likely siblings.

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

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

The description gives explicit when-to-use guidance: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It also recommends event mode for a specific market and names an alternative for custom sizing: 'For custom sizing use polymarket_fill_risk.' This goes beyond minimal context and clearly directs the 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral context: model family details, response structure (by_segment, diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, etc.), the 24h-move warning, caching behavior, and knob interactions. This goes far beyond annotations, providing deep transparency into how the tool behaves.

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 quite long but is well-structured with section labels and parenthetical asides. It is front-loaded with the core purpose, then systematically details model families, response fields, knobs, and diagnostics. While some details (e.g., per-sport α values) could be considered excess, every sentence contributes to understanding the tool's behavior, and the organization aids scanability. Slightly verbose but 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?

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: top-level response structure (by_segment, fed_candidates/fed_note, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread, volume, 24h warning), and caching behavior. It also explains why segments may be empty via diagnostics. This is complete for a complex tool with 9 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?

Schema coverage is 100% with well-described parameters, but the description adds critical interaction semantics that the schema alone lacks. For example, it explains that min_partition_leg_kelly applies to per-leg Kelly because partition arbs return kelly_fraction_half=0 at parent level, and that min_liquidity/max_spread_pp act as tradeable-edge filters. This enriches understanding of how knobs affect output.

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

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

The description opens with a specific action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also states the intended use case ('what should I bet on today') and distinguishes the tool from siblings by focusing on opportunity discovery across model families rather than pure arbitrage or historical tracking.

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

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

The description clearly communicates when to use the tool ('Built for what should I bet on today') and provides context about what the tool returns, including exclusions (Fed bets are surfaced but excluded from ranking due to unreliable signals). However, it does not explicitly name sibling alternatives or state when not to use this tool in favor of another, so it falls short of a 5.

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

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

Annotations already declare readOnly and idempotent hints. The description adds significant behavioral details: history is bounded by a 60-day snapshot TTL, decay is computed from daily closes (not intraday), and snapshot gaps indicate days with no scans. 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 long but well-organized with 'Args:', 'RESPONSE:', and 'LIMITS:' sections. The first sentence conveys purpose immediately. Each sentence carries information, though it could be tighter. 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?

With no output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]) and includes limits. It covers data semantics, edge cases (gaps), and historical depth, making it self-sufficient for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions for both days and window. The description repeats defaults (14, 1wk) and adds 'max 30' which is already in the schema as clamp 2-30. No new parameter meaning is added, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and explicitly answers 'how long has this edge existed and is it shrinking?' It differentiates from siblings like polymarket_edges by focusing on time-series persistence and decay.

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

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

The description provides clear usage context: when you need to distinguish a fresh wide edge from an old one ('a fresh wide edge and a 3-week-old wide edge are different trades'). It does not explicitly name alternative tools, but the context implies when this telemetry is relevant. No exclusions are stated.

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

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

The description richly details behavior beyond the annotations: it walks the order-book ladder, computes VWAP fill price, slippage, shares filled, max fillable, and a verdict; for baskets it returns per-leg details, thin legs, and forced directional risk. It also explains default behaviors and the risk of partial fills. No contradiction with annotations.

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

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

The description is long but tightly structured: a one-line summary, a REQUIRES note, separate SINGLE-MARKET and BASKET sections, and a usage directive. Every sentence conveys necessary operational detail; no filler or redundancy.

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

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

Given the tool's complexity (two modes, 4 parameters, no output schema), the description is exceptionally complete. It enumerates return values (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.), explains behavior for both modes, notes defaults and clamps, and provides context on when the tool is necessary. The agent can select and invoke this tool correctly without additional information.

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

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

While schema coverage is 100%, the description adds critical semantics: size_usd is clarified as 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional — shares per leg' in basket mode, including default and clamp. Side auto-selection in basket mode is explained. market and event are clearly mapped to modes.

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

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

The description opens with a specific, informative statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly defines the tool's function, differentiates from siblings by naming polymarket_arbitrage and polymarket_edges, and distinguishes two distinct modes (single-market and basket).

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' with a rationale explaining why (theoretical overround not capturable on thin books, partial fills create unhedged directional risk). It also clarifies when to use single-market vs basket mode.

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

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

Annotations already declare readOnly and idempotent, so the bar is lower, but the description adds substantial behavioral insight: it explains compatibility_warning conditions, temporal_alignment and its implication for meaningful spreads, skipped_cross_type/subtype semantics, and the reality that many pairings yield no tradable spread. This goes far 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 long and dense, but it is well-structured with clear sections: core definition, two modes, response fields, and safety fields. Every sentence adds necessary context, though a few areas (e.g., detailed skipped_cross_type examples) might be slightly over-specified. It remains organized and front-loaded with the core 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?

With no output schema, the description fully compensates by explaining response components (leg-by-leg prices, spread, compatibility_warning, temporal_alignment, skipped counters) and their interpretations. It covers edge cases such as matched_pairs:0 and temporal misalignment, making the tool's behavior predictable and complete.

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

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

Schema coverage is 100% with all three parameters described, but the description adds significant meaning: it lists all valid topic shortcuts, explains how explicit tickers/slugs override the topic-mapped side, and clarifies the distinction between pre-mapped and explicit modes. This enriches the schema substantially.

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

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

The description clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, using a specific verb ('Cross-venue spread') and resource. It also distinguishes from siblings like polymarket_arbitrage by focusing on venue discrepancies and explicitly outlining two modes (topic shortcuts and custom pairing).

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

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

The description provides clear when-to-use context: use pre-mapped shortcuts for speed or explicit ticker/slug for custom pairings. It warns that most pre-mapped topics currently return compatibility warnings and that pre-mapped ≠ tradeable, which is effective usage guidance. However, it does not explicitly name alternative tools or state when NOT to use this tool in favor of others.

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

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

Annotations already cover read-only and idempotence, so the description only needs to add extra context. It adds that the tool 'Returns attribute rows (and geometry)' and suggests a sampling pattern. This is useful, but it does not disclose any further behavioral traits like error handling or pagination edge cases. A 3 is appropriate given the annotation coverage.

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

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

The description is two sentences plus a practical tip. It front-loads the core purpose and lists all relevant parameters without redundancy. Every sentence adds value, and it is appropriately concise.

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

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

With schema covering all parameters and annotations covering safety, the description provides the essential return-type information and a usage hint. It does not fully elaborate on potential pagination behavior or error cases, leaving a minor gap, but it is sufficiently complete for a query tool with rich structured metadata.

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 each parameter has a description. The tool description summarizes the parameters (e.g., 'comma-separated out_fields') but adds little beyond the schema. The sampling tip is more of a usage guideline than parameter semantics. Thus baseline 3 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 states a specific verb and resource: 'Query an ArcGIS Feature Service / Map Service layer by its url'. It also lists the key query parameters and clarifies the return type, distinguishing it from sibling tools like layer_info (metadata) and search_datasets (dataset discovery).

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

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

It provides clear context by mentioning the url comes 'from search_datasets', implying a workflow. The tip 'Use where="1=1" + out_fields="*" to sample' gives practical usage guidance. However, it does not explicitly contrast with alternatives like layer_info or search_within, so it stops short of a full when-not-to-use explanation.

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 annotations already declare readOnlyHint and idempotentHint, so the description adds valuable context beyond these: scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the optional behavior of listing all keys when the key argument is omitted. It also clarifies the memory lifecycle with remember and forget. 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 two sentences, front-loaded with the primary action and followed by usage context and scope. Every sentence earns its place, with no redundant information or filler.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete: it explains the operation, the parameter behavior, the scoping rules, and the relationship to sibling memory tools. The annotations cover safety, so no further behavioral disclosure is necessary.

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

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

Although schema coverage is 100% with a clear description for the key parameter, the tool description reinforces and expands by explicitly stating 'omit the key argument' to list all keys, adding behavioral meaning beyond the schema definition. This clarifies the optionality and dual-mode functionality.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys'. It also provides concrete examples of stored context (target ticker, address, research notes), making it easy to distinguish from sibling tools like remember and forget.

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

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

The description explicitly states when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions the sibling tools for related operations: 'Pair with remember to save, forget to delete,' effectively providing alternatives and exclusions.

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

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

Despite annotations already covering safety, the description adds significant behavioral detail: alerts carry citation_uri and raw payload, mark_read mutates read-state so next call returns newer events, polling is safe, and the same feed is available via HTTP. This goes well beyond the annotations and is transparent about side effects.

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?

Five concise sentences, front-loaded with the purpose. Every sentence delivers distinct value (return type, fields, filtering, mark_read, polling/HTTP alternative) without redundancy. Highly efficient for the information it conveys.

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 what the tool returns (source, citation_uri, raw payload), filtering, mark_read behavior, and even an external fallback. With no output schema, it adequately describes return items. Slight gap: it doesn't explain how unread_only interacts with mark_read, but the schema covers that parameter.

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 enriches meaning by exemplifying type (e.g. 'sec_8k'), clarifying the since parameter as ISO timestamp, and explaining the consequence of mark_read (next call shows only newer events). It does not cover limit or unread_only, but those are well-defined 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 opens with 'Pull fired events from your subscription feed,' which clearly states the tool's action and resource. It distinguishes this tool from siblings like list_subscriptions by focusing on fired alerts, not subscriptions themselves, and mentions specific payload fields.

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

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

It provides concrete usage context: filtering by type/since, using mark_read for polling, and explicitly notes an alternative HTTP endpoint for scripts/dashboards. However, it does not contrast with sibling tools like recent_changes, but the polling guidance and endpoint alternative are sufficient.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds substantial behavioral detail: fan-out to three sources, GDELT-to-GNews fallback on rate limiting/5xx, USPTO soft-fail due to PatentsView API sunset, and the return structure with pipeworx:// citation URIs. No contradiction with annotations.

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

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

The description is a single dense paragraph that packs a lot of valuable information: query examples, sources, fallback logic, parameter formats, return shape, and an alternative tool. It is not overly verbose, but the density could be slightly improved with bullet points or clearer separation of sections, so it earns a 4 rather than 5.

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

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

Despite having no output schema, the description fully compensates by naming the return fields (changes[], total_changes, pipeworx:// URIs), explaining source behavior, and giving fallback and alternative-tool guidance. An agent has enough context to select this tool, set parameters correctly, and interpret the result.

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

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

Although schema coverage is 100%, the description adds practical parameter guidance: it explains that 'since' accepts ISO dates or relative shorthand like '7d' and '3m', and clarifies that 'value' can be a ticker or zero-padded CIK. The type restriction to 'company' is reinforced, going beyond the schema's enum.

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

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

The description uses a specific verb phrase ('change feed for a company') and clearly names the sources (SEC EDGAR, GDELT/GNews, USPTO) and the output (changes[] with total_changes and citations). It differentiates itself from sibling tools by explicitly directing users to entity_profile for static profiles.

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

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

It provides explicit example intents ('What's new with X', 'latest on Y') and states the window format. It also says to use entity_profile instead when a static profile is needed, which is a clear alternative. The fallback behavior between GDELT and GNews is described, helping the agent decide when to call 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 annotations already mark the tool as idempotent and non-destructive, and the description adds valuable behavioral context beyond these: key-value storage, scoping by identifier, and the difference between authenticated users (persistent memory) and anonymous sessions (24-hour retention). This helps the agent anticipate data persistence behavior without contradicting any annotation.

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

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

The description is front-loaded with the core action, then provides usage guidance, storage model, and companion tools—all in five compact sentences. Every sentence contributes meaning, and the examples are illustrative without unnecessary filler. It is appropriately sized for a simple two-parameter 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?

For a simple key-value memory tool with no output schema, the description fully covers the value proposition, when to use it, persistence semantics, authentication differences, and related tools. It gives an agent everything needed to decide when and how to invoke it, with 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?

The input schema fully documents both parameters (key and value) with examples and descriptions, so the description need not repeat them. The description adds general context about the key-value structure but does not enhance parameter-level detail beyond what the schema provides. Baseline 3 is appropriate given 100% schema description coverage.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later — across this conversation or across sessions.' It identifies the action (save), resource (key-value data), and scope, and distinguishes itself from sibling tools by explicitly pairing with 'recall to retrieve later, forget to delete.' Examples of what to store (resolved ticker, target address, user preference) further clarify intent.

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

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

The description explicitly says when to use the tool ('Use when you discover something worth carrying forward'), providing concrete example use cases. It names companion tools (recall and forget) for retrieval and deletion, but does not give explicit 'when not to use' guidance or contrast with other storage/search tools. This is clear context but not exhaustive exclusion.

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

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

Beyond the readOnly/idempotent annotations, the description richly discloses behavior: cross-source identity spine, source labeling, explicit unresolved identifiers, graceful degradation when GLEIF/OpenFIGI are unavailable, and internal cascading that replaces multiple lookups. This gives the agent reliable 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 long but densely packed with useful information, using clear section labels (SUPPORTED TYPES) and examples. Every sentence adds value, though it could be tightened without losing critical guidance.

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

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

Given the tool's complexity, the description covers important contextual aspects: what identifiers are returned, how unresolved identifiers are handled, and graceful degradation. Without an output schema, it could benefit from stating the return format more explicitly, but it is adequate for agent use.

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

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

The schema already provides full coverage for both parameters, including valid enum values and concrete examples for the value field. The description adds no additional parameter-level semantics beyond restating the type and value options, so baseline 3 is appropriate.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers required by other tools. It gives concrete example queries and explicitly distinguishes itself from siblings by being the first step when a name needs an ID. The supported types are enumerated with details.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID,' which is strong when-to-use guidance. However, it does not explicitly name alternative tools or state when not to use this tool, leaving a minor gap in exclusion criteria.

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

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

Annotations cover read-only and idempotent safety. The description adds valuable context that it probes each entity via ai_visibility_check, ranks by score, and returns per-entity metrics (score, confidence, signal density). No contradiction with annotations, though it doesn't discuss failure handling or rate limits.

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

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

Three tight sentences: main function, method (probes via ai_visibility_check), ranking, use case, and return fields. No fluff, front-loaded with the core action.

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

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

For a composite tool with no output schema, the description sufficiently explains return structure (ranked list with score, confidence, signal density) and the multi-entity behavior. It lacks details on edge cases like partial probe failures or tie-breaking, but expectations are otherwise 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 documentation covers 100% of parameters, so the description adds little beyond what the schema already states. The description's 'your brand + N competitors' indirectly reinforces the entities semantics already in the schema, but no new parameter-specific meaning is introduced.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, explicitly naming the underlying probe (ai_visibility_check) and the output (ranked list). This distinguishes it from single-entity tools like ai_visibility_check and generic comparison utilities.

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 a specific use case ('competitive AI-marketing audits') and an example question ('does Claude know about us as well as our competitors?'). It also implies the alternative ai_visibility_check for single-entity checks, but does not explicitly state when not to use it or contrast with compare_entities.

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

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

The description goes beyond the readOnlyHint and idempotentHint annotations by detailing fan-out behavior, partial failure degradation (bundlephobia timeouts with sources_failed), and latency expectations (5-30s for first measurement). This equips the agent with realistic behavioral context.

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

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

The description is dense but structured: it opens with the composite purpose, then usage, then return fields, then ecosystem scope and failure behavior. Every sentence adds value, but it is a bit long and could be tightened. It earns a 4 for being well-organized without redundancy.

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

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

Despite lacking an output schema, the description enumerates the return fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), plus per-advisory detail, links, and alternatives. It also covers ecosystem limitations and error handling, making it highly complete for a composite tool.

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

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

The input schema already provides full descriptions for both parameters (package, version). The description adds contextual usage examples ('what does adding lodash cost me') and ecosystem constraints, but doesn't specify parameter-level syntax or format beyond the schema. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description clearly states the tool's purpose: a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia. It specifies what it measures (license, advisories, version history, bundle size, dependency count, ESM/tree-shake support) and distinguishes itself from siblings by being npm-specific.

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

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

Explicit usage guidance: 'Use whenever an agent asks is X safe / popular / small' or 'what does adding lodash cost me'. Also provides an exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This clearly states when to use and when not to.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value beyond annotations by specifying the exact return fields (name, summary, record_count, owner/org, url) and the open-data nature of the datasets. It does not contradict any annotation.

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

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

The description is two sentences, front-loaded with the action and resource, and every sentence earns its place. It is concise without sacrificing necessary detail about return values and next steps.

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

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

Despite lacking an output schema, the description fully explains what the tool returns (name, summary, record_count, owner/org, url) and how to use that output with downstream tools. Given the tool's simplicity and rich annotations, this is complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific semantics beyond what the schema describes, but it does contextually link the output url to query_layer/layer_info, which is minor extra value.

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

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

The description clearly states the verb 'Search' and the resource 'City of Charlotte GIS open geospatial datasets', and it specifies the search dimension ('by keyword'). It distinguishes itself from sibling tools by mentioning it returns Feature Service URLs for use with query_layer/layer_info.

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

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

The description gives clear context for when to use the tool (discovering open datasets by keyword) and explicitly directs the user to pass the returned url to query_layer/layer_info. However, it does not mention alternative tools or when not to use it, so it misses the explicit exclusion criterion for a 5.

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

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

Discloses truncation at 200K chars (flagged), the embedding model (BGE-base-en), window size (500-char), and that results include offsets and similarity scores. This goes beyond the readOnly/idempotent annotations and adds valuable behavioral context. 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?

Three dense sentences, front-loaded with the core action, then a use-case/alternative, and finally technical details. Every sentence earns its place with no fluff.

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

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

Even without an output schema, the description explains the return format (top-N passages with offsets and similarity scores), the 200K cap/truncation flag, and pairs with ask_pipeworx_grounded. It is fully self-sufficient for an agent to decide and use the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning for 'text' (already-fetched document) and 'query' (example phrasings), and clarifies 'limit' as 'top-N passages'. It adds some value but does not fully compensate 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 'Semantic search INSIDE a fetched record' — a specific verb+resource+scope. It distinguishes from sibling tools by emphasizing that search happens on text the agent has already pulled, not external sources.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and names the alternative 'ask_pipeworx_grounded' for grounding over passages. This gives clear when-to-use and alternative tools.

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

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

The description goes well beyond the annotations by disclosing important operational behaviors: requiring a Pipeworx OAuth account, returning a subscription id, the always-on feed, phone verification for SMS, a 10/day SMS cap, and webhook auto-disabling after 10 consecutive failures. These details provide critical context for the agent to invoke the tool correctly and set 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 front-loaded with the core purpose and then follows with requirements and supported types. It is a single dense paragraph with many useful details, but it could be broken out into structured lists for improved scanability. Each sentence contributes meaningful information, so it is not wasteful.

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

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

For a tool with multiple subscription types, delivery channels, and no output schema, the description covers the essential aspects: return value (subscription id), auth prerequisites, delivery behaviors, and alternative consumption methods. It is complete enough for an agent to understand what to expect and how to handle the response.

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

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

The schema has 100% coverage with detailed parameter descriptions, but the tool description adds even more semantic value with concrete examples for each subscription type (e.g., items:["5.02"] = officer change) and additional constraints like the SMS cap and webhook auto-disable that are not fully captured in the schema. This significantly enhances parameter understanding beyond the structured data.

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

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

The description clearly states a specific action ('Create a proactive monitoring subscription') and identifies the resource ('live-data event stream'). It distinguishes the tool from siblings like list_subscriptions and unsubscribe by emphasizing the creation lifecycle step, making the purpose unambiguous.

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

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

The description provides clear context for when to use the tool (e.g., monitoring specific event types) and gives examples for each supported type. It also mentions alternative ways to consume alerts via the persistent feed (recent_alerts or GET registry.pipeworx.io/alerts.json). However, it does not explicitly name sibling tools as alternatives, so it lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful context about the return value (category-bucketed example questions with tool+argument shape, drawn from live catalog) and the ability to focus by topic, going 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 dense paragraph that front-loads example queries, then explains purpose and usage. Every sentence provides relevant info, though it could be better structured with line breaks; still appropriately sized.

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

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

For a tool with one optional param and no output schema, this covers what it returns, how to call it, and when to use it. It even lists the categories and examples, making it fully self-contained.

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

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

The schema already fully documents the `topic` parameter with all valid values and behavior (omit for cross-category). The description merely repeats examples (finance, pharma, betting) and adds no new semantic detail, so it stays at the baseline for high schema coverage.

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

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

The description clearly identifies this as the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It uses specific verbs like 'Returns' and 'suggest questions', and distinguishes from other tools by framing it as the 'first' use for agents that don'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?

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and describes how to call with no arguments vs. with a `topic`. It does not explicitly name alternative tools or when-not-to-use, though the 'first' language implies it's the entry point.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description explains that the row is deactivated rather than deleted and that historical events remain available via recent_alerts. This adds meaningful context about the mutation's effect and 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 two sentences, front-loaded with the action, and contains no redundant information. Every sentence contributes to understanding the tool's behavior.

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

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

For a single-parameter mutation with no output schema, the description covers the purpose, ownership constraint, deactivation behavior, and points to recent_alerts for historical visibility. This is sufficiently complete for an agent to use the tool correctly.

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

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

The only parameter id has full schema coverage (100%), with a description referencing subscribe. The tool description reiterates 'by id' but adds no new semantic details beyond the schema, so the baseline of 3 applies.

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

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

The description uses the specific verb 'Cancel' with the resource 'subscription' and the method 'by id', clearly distinguishing it from sibling tools like subscribe and list_subscriptions. It also adds ownership enforcement, making the purpose unambiguous.

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

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

The description provides clear context by stating ownership enforcement ('you can only cancel your own subscriptions'), which implicitly excludes cancelling others' subscriptions. It also points to recent_alerts for historical events, but it does not explicitly name alternative tools for listing or creating subscriptions.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable nuance beyond annotations, especially distinguishing 'could_not_verify' (check did not happen) from 'unsupported' (no source exists), and disclosing that the tool returns a verdict, actual value with citation, and reasoning. It also explains the replacement of 4–6 sequential calls, giving a clear behavioral contract.

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 every sentence serves a purpose: trigger phrases, usage context, path routing, return values, and error semantics. It is front-loaded with the essential purpose and structured into clear segments (usage, paths, output, caveats). No filler or redundancy.

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

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

With no output schema, the description fully explains return values (verdict types, actual value, reasoning) and error cases (could_not_verify vs unsupported). It also covers both execution paths and the tolerance override feature. Given the tool's complexity, the description is complete enough for correct invocation and interpretation.

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 descriptions cover both parameters at 100%, so baseline is 3. The description adds extra meaning, particularly for tolerance_pct: it explains how it overrides implied tolerance and provides guidance for hallucination detection ('set 1–2 for hallucination detection'). This goes 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 verifies natural-language factual claims against authoritative sources, with explicit trigger phrases. It distinguishes between company-financial claims using SEC EDGAR and other claims using a grounded pipeline, and differentiates itself from sibling tools by focusing on fact-checking (e.g., 'fact check', 'verify the claim').

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains when the structured vs grounded paths apply. It also clarifies that 'could_not_verify' means the check failed and should not be shown as evidence. However, it does not explicitly mention when NOT to use the tool or name alternative sibling tools such as deep_research.

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