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?

With readOnlyHint, openWorldHint, and idempotentHint already present, the safety profile is covered by annotations. The description adds value beyond them by disclosing that the tool is a dispatcher which auto-fills arguments, and that results come back as structured answers with citation URIs. It explicitly discloses the 'even if web search could also answer it' behavior. No failure-mode or citation-rendering details are given, but nothing contradicts 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 (~220 words) but front-loaded with the key routing decision ('PREFER OVER WEB SEARCH') and organized in a logical flow: positioning, behavior, triggers, examples, sibling routing. The domain list and examples earn their place for a meta-tool spanning 5,798 tools. The alias sentence is redundant with the fully-covered schema and could be trimmed, preventing a 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?

For a tool with one required parameter, rich annotations, and no output schema, the description covers invocation essentials: what to pass (a natural-language question), what happens internally (routing and argument filling), and what to expect back (structured answer with pipeworx:// citation URIs). The only gap is guidance on how to surface citations to the end user, which is a presentation concern rather than an invocation blocker.

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% — the question parameter and all five aliases (q, text, input, query, prompt) are already documented in the schema, so the baseline is 3. The description's final sentence about aliases largely duplicates that schema information. It adds no format, length, or quality constraints beyond what the worked examples already convey.

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 behavior: it routes the question to the right one of 5,798 tools across 1,517 verified sources, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. This clearly distinguishes it from the generic 'ask' name and from its siblings (ask_pipeworx_beta, ask_pipeworx_grounded). The domain enumeration plus six concrete examples make the scope 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?

Gives explicit trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), an affirmative over-inclusion rule ('even if web search could also answer it'), and a default routing instruction ('START HERE for most questions'). It names two alternatives with their selection conditions: ask_pipeworx_beta for faster/cheaper, ask_pipeworx_grounded for grounded citations to incumbent providers. This is the strongest possible when-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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that candidate routing improvements can be enabled live, that no candidate is currently active, that the tool currently behaves exactly like ask_pipeworx, and that it does not fall back to another tool. This gives the agent a strong, honest model of experimental behavior.

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

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

The description is dense but every sentence earns its place: it defines the tool, explains the experimental status, states current behavior, gives usage direction, and clarifies the fallback misconception. The most decision-relevant information is front-loaded.

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 5,798-tool router and the lack of an output schema, the description is complete enough: it explains current state, relationship to the stable router, response shape parity, and that the tool is fully functional. No critical context for correct invocation appears to be 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 coverage is 100% and every parameter is already documented as an alias for question, so the schema fully explains the parameters. The description only says 'same arguments' and adds no additional parameter-specific meaning, which matches 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 the tool as the beta version of ask_pipeworx, a universal router that handles the same 5,798 tools with the same arguments and response shape. It also distinguishes it from the stable ask_pipeworx by emphasizing the experimental routing improvements and current no-op status.

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

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

The description gives explicit guidance: use it like ask_pipeworx when you want the newest routing, and results are compared against the stable router. It clearly names the stable alternative and the condition for choosing this beta tool, though it does not explicitly state when to avoid it or contrast it with ask_pipeworx_grounded.

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, and idempotent behavior, and the description adds substantive context beyond those flags. It details the extraction method, the exact success and refusal response shapes, the specific refusal reasons, and the extra cost versus the sibling. This is exactly the kind of behavioral disclosure that improves agent trust and correct invocation.

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 grounding behavior, then response contracts, then usage guidance and cost tradeoff. Every sentence delivers useful information with no filler. The length is justified by the complexity of the grounded-mode contract and refusal semantics.

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 fully specifying both success and refusal return contracts, including field names and refusal reasons. It also covers cost, routing relationship to the sibling, and representative high-stakes use cases. An agent has everything needed to invoke and interpret the result 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 documents the question parameter and all aliases with 100% coverage, so the schema fully carries parameter semantics. The description adds no additional parameter-level detail; it only frames the question indirectly via the 'Ask' verb. This meets the baseline but does not exceed it.

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

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

The description clearly identifies this as a hallucination-resistant, grounded answer mode for high-stakes reads, and explicitly distinguishes it from the sibling ask_pipeworx. It states a specific verb/resource combination: extract an answer only from tool results, with refusal when data is insufficient. This makes the tool's purpose unmistakable and separable from sibling tools.

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

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

The description explicitly states when to use this tool: whenever an answer will be quoted, cited, or acted on, and in high-stakes domains like financial verdicts, legal claims, and medical lookups. It also provides a clear exclusion — prefer ask_pipeworx for casual lookups — and explains the tradeoff of one extra LLM call. This leaves no ambiguity about selection.

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

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

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 readOnly/openWorld/idempotent hints and non-destructive behavior, so the bar is higher. The description still adds meaningful behavior beyond annotations: parallel facet decomposition, the findings packet structure (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation), explicit gaps[], tier-specific hop behavior, semantic excerpting of large records, and latency expectations. Minor deduction for not covering failure modes 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?

The description packs a lot of information but is dense and cluttered, with the auth note awkwardly embedded in the opening parenthetical. It is not well front-loaded for scannability, though every sentence does earn its place. A restructured version with clearer rhythm would score higher.

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

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

For a tool with 2 parameters, no output schema, and rich annotations, the description is unusually complete. It covers what the tool does, what it returns, how it handles unanswerable facets (gaps[]), timing expectations, tier differences, auth requirements, and alternatives to siblings. Nothing essential 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 baseline is 3. The description adds real value by explaining what the depth values mean behaviorally (quick=3 facets, standard adds gap-recovery + contradictions, thorough adds a full iterative hop) and clarifying that 'question' can be broad/multi-part. This goes beyond the schema's enum descriptions.

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

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

The description states a specific verb ('research') and a precise resource ('Pipeworx's 1517 STRUCTURED data sources'), explicitly distinguishes itself from open-web search, and gives concrete example questions. It clearly separates deep_research from siblings like ask_pipeworx and compare_entities.

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 this tool ('Best for broad/multi-part questions over structured data'), when not to ('For a single lookup use ask_pipeworx instead'), and even an auth-based fallback ('If you are not signed in, use ask_pipeworx instead'). This is direct routing guidance with named alternatives.

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

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

The description discloses 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 mark readOnly/openWorld/idempotent, and the description adds substantial behavioral context: it explains fan-out across sources, soft-failure of the USPTO API, expected empty sections (FDA products for small-molecule companies), sources_used/sources_failed semantics, and private-company resolution behavior. This goes far beyond the annotations and prevents misinterpreting empty results as bugs.

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?

Although long, the description is dense and every sentence carries operational value: call examples, precedence guidance, source list, return field details, failure semantics, and input parsing rules. It is front-loaded with the most important usage guidance and remains well-organized despite covering a complex multi-source tool.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It specifies the nature of each returned section, failure modes, empty-result meaning, and the resolved:false case. An agent can invoke the tool correctly and interpret all major outcomes without additional context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying that the `type` field accepts 'company' or 'ticker' interchangeably, providing callable examples, specifying zero-padded CIK format, and explaining private-company behavior. This enriches the schema without redundancy.

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 function: returns a full cross-source profile of a US public company in one parallel call. It includes concrete query examples, enumerates all data sources, and explicitly contrasts with chaining single-pack lookups, which distinguishes it from sibling tools like resolve_entity and deep_research.

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

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

It explicitly states when to use the tool ('ALWAYS PREFER ... when the user asks for a holistic view') and names the alternative pattern to avoid ('over chaining single-pack SEC/XBRL/news lookups'). It also gives exclusion criteria such as private companies and non-US entities, making the routing decision 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?

Given that annotations already mark readOnly/openWorld/idempotent, the description adds substantial beyond-annotation context: the token-overlap matcher with limitations, safety fields that can be non-empty even with matches, fee disclosure ('gross, not a net tradeable edge'), and detailed handling of unclassified legs and skipped comparisons. 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 tool description is thorough but long and somewhat redundant. The core purpose is front-loaded, but details like temporal_alignment_unknown are explained both in the safety codes list and later in the temporal_alignment paragraph, and 'BOTH modes' is repeated. All sentences are informative, but tighter organization would improve 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?

Despite having no output schema, the description fully covers response contents, safety fields, flags, fee caveats, skipped counters, and edge cases. An agent can reliably infer what to expect and how to interpret results in both modes. Nothing essential is missing for correct invocation and result 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?

Although the schema already covers all 3 parameters, the description enriches them heavily: it explains that `topic` shortcuts auto-fetch matching events, that explicit `kalshi_event_ticker` and `polymarket_event_slug` override the topic-mapped side, and that both modes run the identical matcher with identical disclosures. This is meaningful behavioral parameter semantics beyond the schema's simple value lists.

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, non-trivial purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes this from arbitrage or live tracking and adds distinct mode semantics (topic shortcuts vs explicit tickers/slugs), making it easy for an agent to understand what the tool uniquely calculates.

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 rich usage guidance: which parameters to use in each mode, how they interact, and when to expect non-tradeable results ('pre-mapped ≠ tradeable'). It warns that most pre-mapped topics return compatibility warnings, helping an agent avoid false expectations. It does not explicitly name sibling alternatives or when-not-to-use conditions, 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 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?

The annotations already declare read-only, idempotent, open-world behavior. The description adds substantial behavioral context beyond those hints: internal cascading lookups replace 2-3 manual calls, identifiers are labeled by source, unresolved identifiers are explicitly listed, ambiguous matches return figi_candidates, and LEI/FIGI enrichment degrades gracefully when external sources are unavailable. 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 densely packed and somewhat run-on, with large parentheticals that reduce scannability. However, each clause contributes useful information—supported identifiers, ambiguity behavior, graceful degradation—rather than filler. It is front-loaded with trigger phrases and the core purpose before expanding into 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?

Despite the absence of an output schema, the description covers what is returned: canonical identifiers, source labels, unresolved fields, figi_candidates on ambiguity, and RxCUI citations. It also explains fallback behavior if GLEIF/OpenFIGI are down. For a tool of this complexity, an agent has enough information to call it appropriately and interpret its results.

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

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

Schema coverage is complete, but the description goes far beyond it: it documents ISIN as a valid company input, shows examples for each type, and warns about passing only the issuer name without trailing security-class words. It also clarifies that a non-ticker instrument can still resolve via name search, which meaningfully enriches the schema's bare parameter descriptions.

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

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

The description states a precise verb-object pair: resolve a user-spoken name into canonical/official identifiers that other tools require. It enumerates supported types and concrete identifier examples (CIK, LEI, RxCUI, FIGI), and its 'Use FIRST whenever you have a name but need an ID' distinguishes it from downstream 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 strong when-to-use signals: explicit natural-language triggers and a direct 'Use FIRST' directive. It does not name an alternative tool explicitly or give a corresponding 'do not use if...' exclusion, but the context of being the pre-step to other tools requiring IDs is clear.

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

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

Annotations 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.