Arcgis Cranston

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds valuable context beyond annotations: default model (Workers AI Llama-3.3-70b free), the requirement to pass _apiKey for Anthropic calls, and the cost implication (BYO key, pay directly). It also describes the return payload shape, which is not in annotations.

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

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

The description is three sentences that are tightly packed with information: purpose, default behavior, parameter nuance, return structure, and use cases. It is front-loaded with the core action and avoids filler, making it easy to scan and process.

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 well by outlining the per-model return object and combined view. It covers default models, API key requirements, and typical use cases. However, the 'combined view' is not elaborated (e.g., what overall metrics it contains), and there is no mention of potential failures or rate limits, so it is not fully complete but sufficient for a read-only probing 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 adds meaning on top of the schema by specifying the default model ('Default model is Workers AI Llama-3.3-70b (free)') and clarifying that _apiKey is only needed if 'anthropic' is included, linking it to the 'models' parameter. This goes beyond the schema entries and helps the agent reason about parameter dependencies.

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 'Probe' and specifies the resource ('one or more LLMs') for a business/brand/product/topic, with a clear scoring output (0-100 per model). It distinguishes from siblings like scan_competitor_ai_presence by emphasizing multi-model probing and per-model scores plus a combined view, making the tool's unique function evident.

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 concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') which clearly indicate when the tool is appropriate. It does not explicitly name alternative tools or state exclusions, so it stops short of the highest bar, but the context is strong and actionable.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it routes to the right tool, automatically fills arguments, and returns structured answers with stable pipeline:// citation IDs. This tells the agent what to expect at a behavioral level. It does not describe limitations like source freshness or rare gaps, but given the annotation coverage, the extra context is valuable.

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 a typical one-liner, but every section earns its place: the 'PREFER OVER...' header, the category list, the routing/clarification mechanism, the trigger phrases, concrete examples, and the deep_research exclusion. It front-loads the most important routing guidance and contrasts each component cleanly. It trails slightly in the example list and the closing line, but on the whole it is tightly packed and useful.

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 absence of an output schema, the description does describe the return format: 'structured answer with stable pipewire:// citation IDs', and it showcases the full usage flow (route, fill arguments, return answer). It also provides a starting point and heads an alternative for the broad/multi-part case. It does not mention sibling variants like ask_pipe503_beta or ask_pipex_grounded, but those are easy to discover alongside; the description provides enough context for an agent to decide and invoke this tool correctly.

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

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

Schema description coverage is 100% — every parameter is documented, with 'question' described as 'Your question or request in natural language. Accepts over 5 main aliases (q, prompt, text, input, query) as synonyms.' The description adds no parameter-level semantics beyond what the schema already provides, so the baseline of 3 applies. The aliases as synonyms are already in the schema, and the tool description just reiterates the natural-language usage.

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

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

The description states a specific verb+resource: it routes natural-language questions to one of 5,596 tools across 1,465 verified sources and returns structured answers with stable pipeworx:// citation URIs. It also explicitly differentiates from alternatives by saying 'PREFER OVER OBJECTIVE' web search and naming deep_research as the sibling for broad/multi-part questions. An agent can clearly tell what this tool does and how it differs from its 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: 'PREFER OVER OBJECTIVE SEARCH for questions about current or historical data', enumerates dozens of covered categories (SEC filings, FDA drug data, FRED/BLS economic statistics, etc.), and lists trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'). It also provides an explicit exclusion: for a broad/multi-part question that should fan out across many tools, 'use deep_research instead'. This leaves almost nothing to inference.

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

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

Adds valuable context beyond the annotations: candidate routing improvements are enabled live, none is presently active, the last was retired on 2026-07-26, and current behavior matches ask_pipeworx exactly. This tells an agent exactly what experimental state it is entering.

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

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

Every sentence earns its place: it defines what the beta is, the current active state, how to use it, and the 'full working router' caveat. Nothing is redundant or padded.

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

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

The description is complete enough for invoking the tool, especially with the schema providing the full alias map and required field. The only gap is that the actual return shape is borrowed by reference to ask_pipeworx rather than specified directly.

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

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

Schema coverage is 100% and the schema itself documents question plus all aliases. The description adds no parameter-specific nuance beyond 'same arguments' as ask_pipeworx, so it stays at the baseline.

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

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

The description clearly establishes that this is a beta version of ask_pipeworx with the same universal routing behavior and response shape. It is specific about being experimental, but it relies on ask_pipeworx being understood to fully define its core purpose.

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

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

States plainly when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing' and warns that it is not a stub by saying 'Falls back to nothing — this IS a full working router.' It distinguishes the beta edge from the stable ask_pipeworx.

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

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

Describes the exact behavioral contract: only uses tool-contained data, produces success output with fields, or refusal with enumerated reasons. It also discloses the extra LLM call cost. Annotation hints (readOnly, openWorld, idempotent, non-destructive) are not contradicted, and the description adds meaningful semantics beyond those 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?

The description is long but every sentence pays off: it explains the mechanism, the output/refusal contract, use cases, and cost tradeoff it avoids marketing filler. It is front-loaded with the core value proposition and uses a compact conditional structure for the return 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?

Even without an output schema, the description compensates by explicitly defining the return fields and refusal reason enum. It covers what the agent needs to know: when to use it, what to expect, and why it differs from its sibling, entirely removing ambiguity.

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

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

The input schema covers 100% of the parameters and provides a clear natural-language alias table, so the description isn't required to restate it. It adds no extra param details, but the schema is sufficiently complete; the question parameter is self-explanatory, so a 4 is warranted.

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

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

It clearly defines the tool's specific use: a hallucination-resistant, grounded answer mode for high-stakes reads, with an explicit description of the pipeline (routing, fetching, extraction) and the final output. It also distinguishes itself from sibling ask_pipeworx through its grounding/evidence emphasis.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on... must not invent facts' and lists example domains. It also directs users away from this variant for casual lookups by saying 'prefer ask_pipeworx for casual lookups', naming the alternative.

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 readOnly, openWorld, idempotent, and non-destructive behavior. The description goes far beyond by disclosing resolver behavior (market_match_confidence, alternatives), news fallback mechanics (_fallback_attempted), safety short-circuiting for low-confidence matches and closed markets, wide-spread tradeability warnings, and cancellation-rule risk. This is a rich behavioral disclosure that supplements the annotations without contradiction.

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

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

The description is long but well-structured with capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.), making it scannable. It front-loads the core purpose and follows with necessary edge-case details. There is some redundancy (e.g., repeated mention of low_confidence_match) and it may be more verbose than strictly needed, but the density is justified by the tool's complexity. Minor over-length prevents 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?

Without an output schema, the description must carry the full burden of explaining return values and side effects. It does this thoroughly: it outlines response shapes (result.market, result.analysis, result.evidence), resolver contract fields, parent-event extraction, news fallback fields, safety statuses (low_confidence_match, market_closed_or_inactive), and resolution-rule risk. It even quantifies edge-case impacts (refund_50_50 ev_impact). This is a complete contextual specification for a complex tool.

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

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

The input schema covers 100% of parameters with detailed descriptions (market formats, depth enum, include_raw behavior). The tool description adds little beyond what the schema already provides for the parameters themselves; it does not explain parameter syntax or defaults further. It does provide examples of fan-out per category, but that is behavioral, not parameter-level semantics. Baseline 3 is appropriate.

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

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

The description opens with a clear, specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also differentiates from siblings by framing the use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and by describing a comprehensive fan-out mechanism that other tools like polymarket_edges or polymarket_arbitrage do not cover.

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 usage context with the 'Use for' list, which tells the agent when to invoke this tool. However, it does not explicitly name alternative tools or state when NOT to use it. It is clear but lacks direct exclusions or comparisons to sibling tools like ask_pipeworx or validate_claim.

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

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

The description adds substantial behavioral detail beyond annotations: it specifies data sources (SEC EDGAR/XBRL, FAERS), handles off-calendar fiscal years (AAPL, NVDA examples), notes sorting by primary metric, and mentions citation URIs. No contradiction with readOnly/openWorld/idempotent 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?

While longer than average, every sentence adds value: query examples, preference rule, data sources, sorting behavior, and return format. It is well-organized and front-loaded with the core purpose and usage cases.

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 entity types, multiple data sources, sorting, citations), the description fully covers input expectations, processing, and output. No output schema exists, so the description appropriately describes the return structure (paired data + citation URIs).

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

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

Schema coverage is 100% for parameters, but the description enhances semantics by providing concrete examples (['AAPL','MSFT'], ['ozempic','mounjaro']), explaining tickers/CIKs vs drug names, and explaining what each type pulls. This goes beyond the schema descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with a specific verb and resource. It distinguishes from siblings by explicitly saying 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and referencing entity_profile alternatives.

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

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

Provides explicit usage guidance with example query phrases ('X vs Y', 'which is bigger') and a direct preference statement over sequential lookups. It also clarifies what each type does, giving context for when to use company vs drug.

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 read-only, idempotent, and non-destructive, and the description goes well beyond by detailing the findings packet (verbatim evidence, confidence, source, fetched_at, citation), explicit gaps[], contradictions[], semantic excerpting of large records, parallel decomposition across 5,596 tools, and expected latency. There is no contradiction with 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, but almost every sentence carries distinct value: auth, alternatives, input style, decomposition, output shape, citation guarantees, depth differences, and latency. It is front-loaded with the most critical sign-in and fallback guidance before the main mechanism.

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 with no output schema, the description communicates key return fields, citation semantics, failure behavior via gaps[], contradictions[], latency expectations, plan requirements, and explicit exclusions. An agent has enough context to decide whether to call this tool and roughly what the response will look like.

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 thoroughly documents both question and depth. The description reinforces the depth behavior (quick/standard/thorough, hop counts, gap recovery) and gives real usage examples, but most parameter-level meaning is already present in the schema, so the additional value is moderate rather than extensive.

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: grounded multi-source research over Pipeworx's 1465 structured data sources in a single call, and even contrasts it with open-web search. It also names the closest alternative (ask_pipeworx), making the tool distinguishable from siblings without opening their schemas.

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

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

It explicitly says to use ask_pipeworx when not signed in, when doing a single lookup, or when dealing with breaking news/open-web topics. It then gives positive usage guidance: broad or multi-part questions over structured data, with concrete examples like comparing regulatory/financial exposure.

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 safety (readOnly, idempotent, non-destructive). The description adds valuable behavioral context: returns top-N results, includes full schemas with curated examples, and results are ready to call without a second lookup. This goes beyond annotations by describing the output format and immediate usability.

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 well-structured. The domain list is slightly verbose but directly informs the user of coverage, earning its place. The 'Call this FIRST' guidance is a strong closing. Minor redundancy between 'browse, search, look up, discover' could be tightened, but overall efficient.

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

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

The description fully compensates for the lack of an output schema by explaining the return value (top-N tools with names, descriptions, and full schemas with examples). It also addresses the broader context of when to invoke this tool among many siblings. For a discovery tool with high schema coverage and clear 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 does not add extra meaning to the parameters beyond reinforcing that 'query' is a natural language description. It mentions 'top-N' but limit is already documented in the schema. No additional semantic value provided.

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

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

Description opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly differentiates from siblings by framing this as the discovery/option-set tool and lists concrete domains. The 'Call this FIRST' phrase further distinguishes it from other tools.

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

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

Explicitly states when to use it ('when you need to browse, search, look up, or discover what tools exist') and provides an exclusionary hint: 'not just one answer' implies if you already know the exact tool, use it directly. This gives clear when/when-not guidance without needing to name 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, open-world, and non-destructive behavior. The description adds valuable behavioral context: patent lookups use the USPTO PatentsView API which sunsets May 2025 and 'soft-fails until reactivated,' and news mentions use a GDELT→GNews fallback. These details go beyond structured data and inform the agent of potential partial failures.

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

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

The description is lengthy but every sentence earns its place. It front-loads with example user queries, then explains the cross-source fan-out, lists return components, and gives input format constraints. The structure is logical: examples → capabilities → returns → parameter notes. No fluff; all statements provide actionable 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?

With no output schema, the description must explain return values, and it does thoroughly: cik + company_name, recent_filings with URIs, fundamentals, patents, news mentions, and LEI. It also covers edge cases like the patent sunset and name-not-supported fallback, making it complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the parameter semantics by giving examples ('ticker "AAPL" or zero-padded CIK "0000320193"') and restating that names are not supported, but it does not add meaning beyond the schema descriptions. The additional example is helpful but does not elevate the score.

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

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

The description clearly states the tool creates a full cross-source profile of a US public company in one parallel call, with specific examples like 'Tell me about X' and 'company profile for Microsoft.' It explicitly distinguishes itself from chaining single-pack SEC/XBRL/news lookups, making the purpose unambiguous and differentiates it from siblings like compare_entities 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?

Provides explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states that names are not supported and points to resolve_entity as an alternative, giving clear when-to-use and when-not-to-use instructions.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true. Description reinforces deletion but adds little beyond that; it doesn't disclose additional behavior like irreversibility or handling of missing keys. 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?

Two sentences, front-loaded with the core action, followed by targeted usage guidance. No wasted words.

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

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

For a one-parameter delete operation, the description covers purpose, usage timing, and sibling tools. The absence of output schema is compensated by annotations; no significant gaps.

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

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

Schema covers the key parameter fully with 'Memory key to delete.' Description's 'by key' adds minimal extra meaning; baseline 3 for high schema coverage 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?

Description clearly states 'Delete a previously stored memory by key,' identifying the verb, resource, and mechanism. It distinguishes from sibling tools remember and recall by indicating deletion versus storage/retrieval.

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

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

Explicitly provides use cases: 'stale context, task done, clear sensitive data.' Mentions pairing with remember and recall, giving contextual alternatives and when to use this tool.

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

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

The description discloses the full workflow ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format') and the output form ('single text blob'). Annotations already declare read-only and idempotent behavior, and the description adds meaningful process detail without contradicting them.

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

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

The description is three sentences with front-loaded action and purpose, followed by a compact list of use cases. Every sentence earns its place, with no redundancy or fluff.

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

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

With no output schema, the description fully explains what will be returned ('a single text blob') and how it should be used. The tool is simple (2 params, no nested objects), and the description covers the process, output, and use cases completely.

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 provides full descriptions for both parameters (url and max_links), so baseline is 3. The description adds only minor context like 'any URL' and 'site-root/llms.txt', but does not introduce syntax or format details beyond the schema. It does not compensate for any gaps because there are none.

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 ('Generate') and resource ('llms.txt file') and clearly states the purpose ('so AI crawlers can index the site cleanly'). It distinguishes itself from sibling tools by specifying the exact output format and common use cases, making it immediately clear what this tool does.

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

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

The 'Useful for' section provides clear contexts (indexing a client's site, drafting your own, auditing a competitor) without explicitly naming alternatives or exclusions. This is clear context but lacks the explicit when-not-to-use guidance that would merit 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 safety (readOnly, idempotent, non-destructive), and the description adds meaningful return-value context: fields with types, geometry type, record count, and capabilities. This goes beyond annotations but does not discuss error conditions or performance implications.

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

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

A single sentence that is front-loaded with the verb and resource, followed by a compact list of returned information. No wasted words 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?

For a simple one-parameter read-only tool with no output schema, the description covers the tool's purpose and key outputs. It names both Feature and Map Services and clarifies the data type returned. The lack of an output schema is compensated by listing the specific information fields.

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

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

The input schema has 100% coverage of the single url parameter, including an example. The description repeats 'by url' but adds no new parameter-level semantics. Baseline 3 is appropriate when the schema handles the parameter documentation.

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

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

The description starts with a specific verb 'Get' and clearly identifies the resource: an ArcGIS Feature/Map Service layer's schema. It lists distinct outputs (fields, geometry type, record count, capabilities), distinguishing it from sibling tools like query_layer which presumably fetch data.

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

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

The description implies usage for retrieving schema/metadata but does not explicitly state when to use this tool versus alternatives like query_layer. No exclusions or alternative tool names are mentioned, so it's clear enough but not fully 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 mark the tool as read-only, idempotent, and non-destructive. The description adds meaningful context by specifying the returned fields and clarifying that only the caller's subscriptions are listed, which goes 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 two sentences, each earning its place: the first defines scope and output, the second gives usage guidance. There is no redundancy or fluff.

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

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

Despite lacking an output schema, the description enumerates return fields, annotations cover safety traits, and usage context explains when to use the tool. For a simple read-only list operation with one optional parameter, this is complete.

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

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

The input schema fully documents the only parameter 'include_inactive' with a clear description, achieving 100% schema coverage. The tool description adds no additional parameter semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and it enumerates the returned fields (id, type, params, etc.). This distinguishes it from sibling tools like subscribe/unsubscribe.

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

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

It provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel.' However, it does not explicitly name alternative tools or state when not to use it, 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 only say readOnly=false and destructive=false, which is minimal. The description adds significant behavioral context: rate-limited to 5 per identifier per day, free and not counted against quota, claim_token retrieval behavior, daily digests, and roadmap signal. This far exceeds what annotations provide and contains no contradictions.

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

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

The description is front-loaded with the core purpose, then logically flows through usage cases, scope exclusion, claim_token mechanics, and rate limits. Every sentence earns its place, containing dense but relevant information no redundant or vague statements.

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 (4 params, nested object, no output schema), the description covers all necessary aspects: purpose, scope boundaries, claim_token lifecycle, rate limits, and feedback content guidance. It completely equips an agent to decide when to use it and how to invoke it successfully.

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

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

Schema coverage is 100%, but the description adds meaning beyond schema: explains claim_token's return/read flow, gives examples for the type enum (bug, feature, praise), clarifies context fields (pack, tool, vertical) via 'describe in terms of Pipeworx tools/packs', and provides message format guidance (1-2 sentences, 2000 chars).

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-resource pair ('Tell the Pipeworx team') and enumerates exact use cases (bug, feature/data_gap, praise). It clearly distinguishes itself from sibling tools by scoping to tools served by this Pipeworx connection and explicitly says it's not for other MCP servers.

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

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

Provides explicit when-to-use guidance (wrong/stale data, missing capability, praise) and an explicit when-not-to-use exclusion (other MCP servers). Also explains how to form feedback and how to use claim_token, giving comprehensive context for selection and invocation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: it is a self-aggregating signal derived from CF analytics-engine, includes no PII, returns only (pack, tool, count), and is cached 5min-1h depending on window. This goes well 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 front-loaded with the tool's purpose, followed by concise use cases and relevant behavioral details. Every sentence earns its place and there is 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?

Despite having no output schema, the description explicitly states what the tool returns (top tools, top packs, total call volume, just pack/tool/count) and covers window choices and caching. The tool is simple and all essential behavioral context is provided.

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

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

Schema description coverage is 100% and the schema already explains the window parameter and its trade-offs. The tool description adds no new parameter-specific semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states what the tool does: it returns top tools, top packs, and total call volume over a window. It distinguishes itself from siblings like discover_tools by specifying that it aggregates calls from other AI agents on Pipeworx, with a self-aggregating signal.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming canonical choices, checking alignment) and explains the window semantics (shorter vs. longer windows). It does not name alternative tools, but provides clear context for when to use this tool.

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

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

Annotations already signal read-only/idempotent, and the description adds rich behavioral details: the Jaccard similarity threshold for semantic pairing, the 20% placeholder filter, the 3pp gap threshold, and the fill-check warning that realizable_edge_pp <=0 means the edge is not in the book. These go well beyond what annotations alone convey.

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 structured and dense, with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that each add non-redundant operational detail. The opening summary and mode guidance front-load the most critical decisions, and every sentence serves a purpose.

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

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

With no output schema, the description explicitly explains return shapes (opportunities[], partition_check), failure conditions (null arb signal, thin_legs[]), and the fill-check warning. It covers all modes, parameter semantics, internal filters, and the follow-up tool, making it fully self-contained for an agent.

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

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

Although schema coverage is 100%, the description deeply enriches both parameters: event gets slug formats and URL acceptance, topic gets seed question examples and cross-event behavior. It clarifies the functional difference between the two modes and explains how each affects scanning and 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 verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool from siblings like polymarket_fill_risk (pricing/sizing) and polymarket_edges by focusing on arbitrage scanning, and it names the three invocation modes.

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

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

Provides explicit when-to-use guidance: no args for trending_scan, 'event' for a specific market, and 'topic' for cross-event scanning. It recommends event mode for specific markets, explains when cross-event mode is advantageous, and names polymarket_fill_risk as the alternative for custom sizing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar for additional transparency is lower. The description goes far beyond, disclosing caching behavior ('Cached 1h at the KV level keyed on all knobs'), output segments, diagnostics (why a segment is empty), edge calculations (net of slippage, Kelly caps), and filter mechanics (placeholder-slug filters, tradeable-edge knobs). This rich detail helps the agent anticipate exactly what the tool returns and how knobs affect results.

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

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

The description is long but front-loaded with the core purpose, then logically organized into segments, knobs, and response top-level. Every section adds valuable detail for a complex 9-parameter tool, though some specifics (per-sport alpha values, prior gate relaxation numbers) may be more than needed for invocation and could be trimmed without loss of essential guidance.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: lists by_segment structure, fed_candidates/fed_note, _diagnostics with funnel counters, and per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.). It also covers edge cases like empty segments and stale markets, making the tool's behavior fully predictable for an agent.

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

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

Schema coverage is 100% so all 9 parameters already have descriptions. The description adds cross-parameter context, e.g., 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable' and 'min_partition_leg_kelly filters partitions by best per-leg Kelly,' which explains how knobs interact and their purpose in the overall edge-selection pipeline. This exceeds the baseline 3 for full schema coverage.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly identifies the tool's niche (edge discovery via model disagreement) and differentiates itself from siblings like polymarket_arbitrage or polymarket_edge_tracker by its focus on Pipeworx data and 'what should I bet on today' use case.

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

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

The description gives explicit context ('discover opportunities without paging hundreds of markets') and includes a clear exclusion (fed bets are surfaced but excluded from ranking due to unreliable 1m-T vs EFFR signal without paid data). However, it does not explicitly name sibling alternatives or state when not to use this tool, though the fed note and knob descriptions imply appropriate filters.

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

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

Annotations already establish the tool as read-only, idempotent, and non-destructive. The description adds significant behavioral context beyond annotations: snapshot timing (cache-miss only), history depth limited by 60-day TTL, decay calculated from daily closes rather than intraday, and the sign convention for edge_pp_net. This fully informs the agent of operational quirks.

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 typical, but it is front-loaded with the core purpose and structured into Args, RESPONSE, and LIMITS sections. Each section provides necessary operational detail, especially since there is no output schema. A few explanatory asides, such as the parenthetical about wide edges, add context but could be trimmed.

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

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

With no output schema, the description fully compensates by detailing the response shape (tracked, expired, snapshot_dates), the meaning of each field, and important limitations (TTL, cache-miss gaps, close prices). The agent has enough information to invoke the tool and interpret results 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%, and the description mostly restates the schema: days as lookback with default 14, window as snapshot family with default 1wk. It adds minimal new meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb and resource: it tracks edge persistence and decay from polymarket_edges snapshots, answering a precise question about edge age and shrinkage. This clearly differentiates it from the sibling polymarket_edges tool, which likely shows current edges rather than historical persistence.

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 when to use the tool: when assessing whether an edge is fresh or old, and whether it is decaying. It contrasts fresh vs. 3-week-old edges, making the use case clear, but it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral detail: walks the order-book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, etc.), interprets size_usd differently per mode, and flags forced_directional_risk and thin_legs. 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 meticulously organized into SINGLE-MARKET and BASKET sections, with each sentence earning its place. It front-loads the core purpose and packs critical details (return fields, defaults, risks) 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 having no output schema, the description enumerates all return values for both modes, explains the meaning of size_usd, includes risk warnings about thin books and partial fills, and provides fallback defaults. For a complex two-mode tool, this is comprehensive.

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

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

Schema coverage is 100%, but the description enriches every parameter: 'market' vs 'event' are mapped to modes, 'side' gets default behavior for each mode, and 'size_usd' is defined as 'max spend on buys' in single-market and 'settlement notional' in basket. This adds meaning beyond the schema's type/description.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from sibling tools like polymarket_arbitrage by focusing on fill risk and realizable edge, and thoroughly explains both single-market and basket modes.

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 when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the consequence of not using it (partial fills convert arb into unhedged directional position), making the usage context 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?

Beyond the read-only, idempotent, and open-world annotations, the description discloses nuanced behavioral traits: it explains how participant pool differences create spreads, how equivalence of bet shapes affects signal validity, and that mismatched shapes trigger safety warnings. It details response fields (matched_pairs, skipped_cross_type, temporal_alignment, etc.) and explicitly notes that real cross-venue spreads are rarer than the shortcut list implies. This is rich context not available from annotations alone.

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

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

The description is long but highly structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and no filler. Each sentence earns its place, covering purpose, usage, output, edge cases, and practical limitations. It front-loads the core purpose, then systematically adds depth 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?

Given three optional parameters, no required inputs, no output schema, and complex domain-specific behavior, the description fully compensates by explaining response contents, safety fields, fallback logic, and interpretation of warnings. It addresses the 'open-world' nature by warning that pre-mapped topics may not yield tradable spreads. Users can confidently understand what the tool returns and when to trust 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?

Although schema coverage is 100% and all three params are described, the description adds significant behavioral meaning by organizing them into two modes and explaining override semantics (e.g., explicit ticker/slug overrides the topic-mapped side). It also lists the exact 10 pre-mapped topic values, going beyond the schema's terse 'Pre-mapped' description. This explains how parameters interact, not just what they are.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' using a specific verb and resource that clearly communicates the tool's unique function. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison. The scope is defined precisely with references to equivalent bet shapes and explicit matching modes.

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 outlines two usage modes ('topic' shortcuts vs explicit event tickers) and provides clear when-not guidance by explaining compatibility_warning scenarios. It warns that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable,' setting realistic expectations for use. It also describes how to interpret mismatches like temporal alignment, which helps users decide if the tool is appropriate for their question.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds that it returns 'attribute rows (and geometry)' and suggests a sampling pattern, but does not discuss pagination limits, performance, or error behavior, which would be extra value beyond annotations. With annotations covering the safety profile, a 3 is appropriate.

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

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

The description is three sentences, front-loaded with the core purpose. Each sentence adds unique value: purpose, parameter list, and a usage tip. There is no wasted or redundant language.

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 partially compensates by stating return content ('attribute rows and geometry'). The annotations provide safety context, and the schema fully documents parameters. It could be improved by mentioning the default limit (50) or max limit, but for a query tool with strong structured metadata, this is sufficient.

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

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

Schema coverage is 100%, with each parameter described in the schema. The description mentions 'SQL-like `where`, comma-separated `out_fields`, `order_by`, `limit`, `offset`', which adds a little context about format, but the schema already provides detailed descriptions. The baseline of 3 applies because 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 the verb 'Query' and resource 'ArcGIS Feature Service / Map Service layer', and specifies the URL source 'from search_datasets'. It distinguishes from siblings like layer_info (metadata) and search_datasets (discovery) by focusing on retrieving attribute rows and geometry.

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 indicating the prerequisite workflow ('from search_datasets') and includes a practical sampling tip ('Use where="1=1" + out_fields="*"'). However, it does not explicitly mention when not to use this tool or name alternative tools for metadata discovery, only implying them.

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, idempotentHint, destructiveHint), the description discloses key behavioral context: scoping to an identifier (anonymous IP, BYO key hash, account ID) and the fact that omitting the key lists all saved keys. It also situates the tool in the remember/forget lifecycle, adding valuable operational transparency.

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

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

The description is three sentences, perfectly front-loaded with the core action in the first sentence, followed by context and usage guidance. Every sentence adds value without redundancy or fluff. It is concise while remaining informative.

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 parameter and no output schema, the description covers all essential aspects: the purpose, the two execution modes, the scoping rule, and how it relates to remember/forget. It leaves no critical gaps for the agent to invoke the tool correctly.

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

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

The schema already covers the 'key' parameter with 'Memory key to retrieve (omit to list all keys)'. The description reinforces this and adds semantic richness through examples (user's target ticker, address, research notes), helping the agent understand what kinds of values are stored. It does not introduce new parameter details beyond the schema, but the examples enhance meaning, so a 4 is appropriate.

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

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

The description opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes the tool from siblings by naming 'remember' and 'forget' as the save/delete counterparts, and it gives concrete examples of stored content (ticker, address, notes), 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?

It explicitly states when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also provides alternatives by pairing with 'remember' and 'forget,' and clarifies the two modes (retrieve vs. list) based on the key argument. This gives clear usage direction and differentiates from sibling 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?

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond this: the return shape (source, citation_uri, raw payload), the side effect of mark_read on subsequent calls, and the availability of the same feed via a public GET URL. It also explicitly states polling is safe, reinforcing the idempotent hint. 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 three sentences, front-loaded with the core purpose. Every sentence provides useful information: the payload contents, filtering options, mark_read behavior, and the external feed endpoint. There is no fluff or redundancy, making it highly 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 carries the burden of explaining return values, and it does: source, citation_uri (pipeworx://), and raw event payload. It also covers key usage patterns (filtering, mark_read, polling) and even provides an alternative access method. The limit and unread_only parameters are already documented in the schema, so no info is missing for an agent to select and invoke this 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 schema covers all 5 parameters with descriptions, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains how mark_read affects future calls ('next call only shows newer ones'), provides a concrete example for the type parameter ('sec_8k'), and clarifies the relationship between since and filtering. This supplemental guidance justifies above-baseline scoring.

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

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

The description opens with a specific verb and resource: "Pull fired events from your subscription feed." It clearly distinguishes this tool from siblings like list_subscriptions (which lists subscriptions, not events) and recent_changes (which tracks changes to a different resource). The additional details about the evaluator writing to a persisted feed and the return payload further clarify the tool's purpose.

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

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

The description gives clear usage context: it mentions filtering by type and since, using mark_read to control subsequent reads, and notes that polling works fine. It also provides an alternative endpoint for scripts/dashboards, indirectly suggesting when to use this tool (agentic contexts). However, it does not explicitly state when NOT to use it or directly compare with alternatives like recent_changes or list_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 readOnlyHint, idempotentHint, and non-destructive. The description adds rich context: parallel fan-out to SEC EDGAR, GDELT/GNews fallback, USPTO soft-fail due to API sunset, and return structure (changes[] grouped by source, total_changes, 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 dense and well-structured: opening with common query phrasings, a clear definition, then key details on sources, parameters, return format, and an explicit alternative. Every sentence conveys unique useful information 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?

For a tool with no output schema, the description compensates by specifying the return shape (changes[] grouped by source, total_changes, citation URIs). It also explains the source fan-out, fallback logic, and the soft-fail condition. Combined with annotations, an agent has complete context for invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description restates the `since` format and hints at its use in the fan-out, but doesn't add significant new meaning beyond the schema. It doesn't elaborate on `value` beyond the schema's examples, so no extra credit.

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

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

The description clearly defines the tool as a 'change feed for a company' covering filings, news, and patents over a time window. It distinguishes itself from sibling entity_profile by stating 'Use entity_profile instead when you want the static profile...' making the purpose unambiguous.

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

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

Provides explicit when-to-use via example queries like 'What's new with X' and 'latest on Y', and gives a direct alternative: 'Use entity_profile instead when you want the static profile...'. It also explains fallback behavior for news sources (GDELT preferred, GNews on rate-limit or 5xx), clarifying expected usage.

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 idempotent and non-destructive behavior, but the description adds valuable context beyond them: key-value storage scoped by identifier, persistence differences between authenticated users (permanent) and anonymous sessions (24 hours). This is meaningful behavioral disclosure not present in 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 three sentences, each serving a distinct purpose: the first states the core function, the second gives concrete usage scenarios, and the third covers storage, scoping, and persistence details. No filler or redundant content; it is appropriately front-loaded and efficient.

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

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

For a simple two-parameter tool with no output schema, the description is remarkably complete. It covers what the tool does, when to use it, how data is stored (key-value scoped by identifier), persistence rules, and how it integrates with sibling tools. 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 coverage is 100% with clear descriptions for both 'key' and 'value'. The description reinforces the key-value pair concept but adds no new parameter-level semantics beyond what the schema already provides. This matches the baseline of 3 when the schema carries the explanatory burden.

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 action: 'Save data the agent will need to reuse later.' It specifies both the verb (save) and resource (data) plus the intended purpose (reuse across conversation or sessions). It distinguishes from siblings by explicitly naming 'recall' and 'forget' and stating how they pair together.

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 when' guidance with concrete examples (resolved ticker, target address, user preference, research subject). Names alternatives directly: 'Pair with recall to retrieve later, forget to delete.' This fully covers when to use and how it relates to sibling 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?

Annotations declare readOnlyHint, idempotentHint true and destructiveHint false; the description adds substantial behavioral context beyond these: it cascades through multiple lookup endpoints, degrades gracefully when GLEIF/OpenFIGI is unavailable, labels identifiers with source, and explicitly includes unresolved identifiers. No contradictions with annotations.

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

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

The description is well-structured, front-loading example queries and the primary instruction. It then details each entity type and graceful degradation. However, it is somewhat verbose, containing detail that could be condensed (e.g., multiple examples in the opening). It remains clear and informative without being excessively long.

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 entity types, multiple identifier sources, no output schema), the description covers input semantics, behavior (cascading lookups), error handling (graceful degradation), and output structure (labelled identifiers, unresolved list). It anticipates agent needs for when and how to use the tool, making it 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 already documents both parameters (type enum, value string) with 100% coverage. The description adds extra meaning: for type 'company' it details the identifiers returned (CIK, ticker, LEI, FIGI) and explains ISIN-to-LEI mapping; for 'drug' it mentions RxCUI and citation. This goes beyond the schema's simple enum and description, earning a 4.

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

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

The description clearly states the tool resolves names to canonical/official identifiers for use by other tools. It provides multiple example queries ('What's the ticker for...', 'find the CIK for...') and explicitly distinguishes its purpose from sibling tools by noting it should be used 'first' when you have a name and need an ID.

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 a direct usage guideline: 'Use FIRST whenever you have a name but need an ID.' It also explains that the tool replaces 2-3 manual lookups, implying it is the right starting point. While it doesn't explicitly list when not to use it, the context of sibling tools (e.g., entity_profile for known IDs) makes the boundary 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 establish the tool as read-only, idempotent, and safe. The description adds valuable behavioral details: it probes a sub-tool (ai_visibility_check), ranks results, and returns specific metrics (score, confidence, signal density). This goes beyond what annotations provide, without contradicting them.

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

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

The description is three sentences, each earning its place: the first states the core function, the second explains the mechanism and ranking, the third gives a practical use case. No redundancy or filler, with the key action 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?

The description covers the core functionality, use case, and return value ('ranked list with score, confidence, signal density'). It does not discuss edge cases or error handling, but given the annotations and schema richness, it is sufficiently complete for a read-only comparison tool.

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

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

Schema description coverage is 100%, so the parameters are already well-documented. The description adds context about the 'subject' and 'competitors' relationship (first entity as subject), but otherwise does not significantly enhance the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the mechanism (probes each entity with ai_visibility_check, ranks by score) and the output (surfaces most/least recognized). It distinguishes from sibling ai_visibility_check by emphasizing the multi-entity comparison aspect.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and an example query, making it clear when to use the tool. It does not explicitly mention alternatives or when *not* to use it, but the context strongly implies this is for comparing multiple entities rather than a single check.

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 readOnlyHint and idempotentHint annotations, the description discloses the composite nature (fan-out across two services), latency risk (bundlephobia first measurement can take 5-30s), and graceful degradation with sources_failed. It also enumerates the exact fields in the summary block, which is valuable behavior context for an agent. This is far more than annotations alone provide.

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

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

The description is dense but each sentence earns its place: the core value proposition ('should I add this npm package…'), the exact use cases, the output contract, the ecosystem limitation, and failure behavior. It is front-loaded with the primary use and avoids redundancy. No wasted words despite 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 delivers: summary block fields, per-advisory detail, links, and recent versions. It also covers operational edge cases like a new version timing out and partial success. For a composite tool with two external dependencies, this is a highly complete description.

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

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

The input schema already documents both parameters with 100% coverage: 'package' (npm package name, scoped packages accepted) and 'version' (specific version, defaults to latest). The description does not add further parameter-specific details beyond what the schema provides, so the baseline score of 3 applies. The mention of NPM ecosystem is a general scope statement rather than a parameter-level clarification.

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 clear, specific purpose: 'Composite "should I add this npm package to my project" check in ONE call.' It names concrete data sources (deps.dev, bundlephobia) and the exact outputs returned, which distinguishes it from generic scan tools. The NPM-only scope further clarifies its identity versus broader ecosystem 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?

It gives explicit trigger scenarios: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides a when-not-to-use directive: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' pointing to an alternative. This is clear usage direction beyond a vague 'use for dependency checks.'

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

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

Annotations already declare the tool read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context by listing the exact return fields (name, summary, record_count, owner/org, url) and explaining how to chain the output to other tools. It does not detail pagination or rate limits, but those are not critical for a search tool.

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 long, front-loaded with the primary action, and contains no fluff. Every clause adds useful information: dataset scope, examples, return fields, and a cross-reference to related tools.

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 search tool with rich schema and annotations, the description covers the tool's purpose, its scope, the output structure, and the recommended next step. No critical information is missing; even pagination or authentication would be redundant given the open data context.

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

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

The input schema has 100% coverage with descriptions for all three parameters. The description does not add new parameter-specific semantics; it only echoes the 'keyword' aspect of the query parameter, which is already in the schema. Baseline 3 is appropriate when the schema fully documents parameters.

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 ('Search'), a specific resource ('Cranston GIS open geospatial datasets'), and a clear scope ('parcels, zoning & city services'). It also distinguishes itself from siblings by noting the returned Feature Service URL is used with query_layer / layer_info, making the tool's role in the workflow unambiguous.

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

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

The description gives clear usage context: it is for keyword-based dataset discovery, and explicitly directs the user to pass the returned URL to query_layer / layer_info for subsequent operations. It stops short of explicitly stating when NOT to use the tool, but the alternative tools are named and the workflow is clear.

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

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

The description adds substantial behavioral details beyond the annotations: it discloses the embedding model (BGE-base-en), search mechanism (cosine over 500-char overlapping windows), a 200K character cap with truncation and flagging behavior, and the output structure (passages with character offsets and similarity scores). These are important operational traits not inferable from 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 slightly longer than necessary but every sentence earns its place: purpose, usage guidance, pairing with a sibling, and behavioral caveats are all addressed. It front-loads the core purpose in the first sentence. The density of information justifies the length, though it could be tightened by merging some clauses.

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

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

Given the tool's moderate complexity (3 parameters, no output schema, and non-trivial search behavior), the description covers all essential aspects: what it does, when to use it, return format (top-N passages with offsets and similarity scores), technical details (embeddings, windowing, truncation), and relationship to sibling tools. Without an output schema, it adequately explains what to expect.

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

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

The schema already provides 100% coverage with clear descriptions for all three parameters, so the baseline is 3. The description adds value by giving concrete examples for 'text' (SEC 10-K body, article, long tool result) and 'query' (natural-language queries like 'supply-chain risk'), and by clarifying the conceptual role of 'text' as 'the text you already pulled.' This enriches parameter understanding beyond the schema alone.

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

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

The description clearly states it performs 'Semantic search INSIDE a fetched record' and specifies the exact mechanics: pass text plus a natural-language query to get top-N passages with offsets and similarity scores. It also distinguishes itself from siblings by naming ask_pipeworx_grounded and explaining a separate workflow ('fetch with the gateway, ground over the relevant passages'). This is a specific verb+resource with explicit sibling differentiation.

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

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

The description provides a clear trigger condition: 'Use when the record is too big to cram into the prompt.' It explains the benefit (saves context, returns only relevant passages) and names a paired alternative (ask_pipeworx_grounded) with a concrete usage pattern. This goes beyond implied usage and gives explicit 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?

Goes far beyond annotations by disclosing the Pipeworx OAuth requirement (anonymous/BYO cannot persist), the always-on feed behavior, SMS verification and 10/day cap, and delivery channel nuances. Webhook details in the schema further enrich transparency. No contradiction with the provided 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 dense single paragraph with front-loaded purpose and organized type/channel details. Some redundancy with the schema exists, but the description remains efficient relative to the volume of contextual 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?

Given no output schema, the description explicitly mentions the returned subscription id. It also covers authentication prerequisites, all supported types, delivery channels, and key limitations. Webhook details are not in the prose but are covered by the input schema, so overall context is complete.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantic meaning beyond the schema by explaining what each subscription type represents (e.g., polymarket_edge = cross-venue mispricings, sec_8k items = officer change) and clarifying delivery behavior. This enriches parameter understanding beyond raw type definitions.

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 'Create a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id,' giving a specific verb and resource. This distinguishes it from sibling tools like unsubscribe and list_subscriptions.

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

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

The description makes it clear this is for creating subscriptions with ongoing monitoring, and it provides context like the feed always being on and pull options. It does not explicitly name alternatives or exclusions, but the use case is unambiguous given the sibling list.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds valuable behavioral context: it returns category-bucketed example questions drawn from the live catalog, each with tool+argument shape, and explains the effect of the optional topic parameter. 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 every sentence earns its place: front-loaded with example user queries, then clear purpose, then parameter guidance, then usage timing. The use of em-dashes and parentheticals keeps it organized. No redundant or filler content.

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

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

With no output schema, the description fully covers return value (category-bucketed examples with tool+argument shape), explains the parameter and its default behavior, and provides usage context and alternatives. Given the tool's moderate complexity, the description is complete and self-sufficient.

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

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

Schema coverage is 100% and the schema already describes the topic parameter's allowed values. The description enhances this by giving concrete examples ('finance', 'pharma', 'betting') and explaining that omitting topic returns a cross-category spread, adding behavior beyond the schema's bare list.

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 specifies a clear verb+resource: it suggests example questions for Pipeworx, explicitly listing onboarding queries like 'what can I ask Pipeworx?' and describing the returned category-bucketed examples with tool+argument shapes. It distinguishes itself from siblings like ask_pipeworx by framing itself as the 'onboarding entry point' for learning what Pipeworx can do.

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

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

Provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also names the meta-tools (ask_pipeworx, entity_profile, compare_entities) as things to learn about, implying this tool is for discovery rather than execution.

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

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

The description adds valuable behavioral context beyond annotations: ownership enforcement, deactivation (not deletion), and preservation of historical events. This complements the annotations (destructiveHint=false) and provides a full picture.

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

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

Two sentences, front-loaded with the action, and each sentence adds a meaningful detail. No redundancy 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 single-parameter tool with no output schema, the description covers purpose, ownership, and data consequences. It is sufficient for an agent to select and invoke the tool correctly.

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

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

The input schema already fully describes the id parameter (type, required, and that it comes from subscribe). The description adds nothing beyond 'by id', so it relies on the schema's 100% 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 states 'Cancel a subscription by id' with a specific verb and resource, clearly distinguishing it from siblings like subscribe and list_subscriptions. The ownership enforcement detail further clarifies scope.

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 on when to use the tool (to cancel a subscription) and implicitly distinguishes from related tools by explaining the deactivation behavior and reference to recent_alerts. However, it does not explicitly mention alternatives or when not to use it.

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

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

Annotations already mark it read-only, idempotent, and non-destructive, but the description adds crucial behavioral semantics beyond that: could_not_verify means the check did not happen and is not evidence for/against the claim, unsupported means no source exists, and a verification_error carries stage/detail. It also discloses the dual pipeline behavior and the tolerance override capability, providing rich context not available in 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?

Although relatively long, the description is front-loaded with the core purpose and examples, then flows into an efficient breakdown of verdicts, error semantics, and pipeline details. Every sentence serves a purpose: the verdict list prevents misinterpretation, the IMPORTANT callout prevents a critical misjudgment, and the pipeline description clarifies what the tool does. 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?

For a tool with only 2 parameters and no output schema, the description is remarkably complete. It covers the two execution paths, enumerates all possible verdicts, clarifies the meaning of error and no-source states, and explains the return format (actual value with citation and reasoning). An agent has everything needed to invoke it correctly and interpret results reliably.

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, but the description adds meaningful guidance for tolerance_pct by explaining that it overrides the implied tolerance and recommending 1–2% for hallucination detection. It also gives concrete claim examples for the claim parameter. This exceeds the baseline but does not radically extend the schema descriptions.

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

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

The description opens with natural-language query examples that immediately convey the tool's purpose: verifying factual claims. It explicitly contrasts the structured SEC EDGAR/XBRL path for company-financial claims with the grounded pipeline for all other claims, clearly differentiating itself from sibling tools like ask_pipeworx or deep_research. It also states that it replaces 4–6 sequential calls, making its role unmistakable.

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

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

The description gives an explicit trigger condition: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains internal routing (financial vs. other) and warns that could_not_verify should not be treated as evidence. However, it does not name alternative tools for scenarios where this tool is inappropriate, only describing when to use it, 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.