Arcgis Aurora

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

Annotations already cover readOnly/openWorld/idempotent hints. The description adds meaningful behavior: cost implications (BYO key, pay Anthropic directly), default model being free, and the return structure with per-model and combined views. This goes beyond what annotations provide.

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

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

The description is two sentences, front-loaded with the core action and outcome, followed by model details, return shape, and use cases. Every sentence earns its place with zero 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?

Given the tool's complexity (external LLM calls, 4 parameters, no output schema), the description covers the essential input, output, cost tradeoffs, and use cases. It omits minor aspects like rate limits or error handling but is complete enough for initial tool selection.

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

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

Schema coverage is 100% and each parameter already has descriptive text (entity, models, _apiKey, context). The description adds practical context (e.g., 'pass _apiKey to also probe Anthropic') but does not significantly extend the schema's meaning, so baseline 3 is appropriate.

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

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

The description clearly states a specific verb ('Probe') and resource ('one or more LLMs') with a measurable outcome ('score visibility 0-100 per model'). It also specifies the output structure, distinguishing it from sibling tools like scan_competitor_ai_presence or deep_research that may serve different purposes.

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

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

The description explicitly lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to add Anthropic via _apiKey. It does not name alternative tools, but the context is clear enough for an agent to infer suitability.

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 that this is a read-only, open-world, idempotent operation. The description meaningfully adds that the tool routes the question across 5,581 underlying tools, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. These details go beyond the annotations and help the agent predict behavior. It does not mention potential latency or how the system handles unsupported questions, so it is not perfect.

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 not short but every sentence earns its place: it front-loads the recommendation, explains routing behavior, provides a rich example set, includes a final 'START HERE' directive, and adds the note about not having to reformulate the question. The examples are useful rather than filler, and the structure is clear.

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

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

With no output schema, the description compensates by describing the return value as a structured answer with stable citation URIs and mentioning the breadth of sources. It covers what an experienced agent needs to know: when to use it, what to pass, and roughly what it returns. It does not offer guidance on failure cases or how to choose it against ask_pipeworx_grounded / beta, so some context 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?

The schema has one semantic parameter, 'question', with six aliases and 100% description coverage. The description adds the practical hint that no schema reformulation is needed, but it does not add anything structurally meaningful beyond the schema's existing alias documentation. At complete schema coverage, this attains the baseline 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 what the tool does: it routes the user's question to a large set of authoritative sources and returns a structured answer with citations. It specifies a precise scope (SEC filings, FDA data, economic statistics, patents, real estate, weather, news, etc.), which makes the purpose concrete. However, it never distinguishes itself from similarly-named siblings like ask_pipeworx_beta or ask_pipeworx_grounded, so it stops short of full 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 gives an explicit preference rule: 'PREFER OVER WEB SEARCH', followed by a clear list of trigger phrases and example topics. It also states 'START HERE for most questions' and explicitly says the tool should be used 'even if web search could also answer it.' This is very strong, explicit guidance with an alternative named and a practical rule for when to select this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read-only operation. The description adds valuable behavioral context: it's a beta router that may have routing improvements enabled live, it currently matches the stable router, and it is a full working router (not a stub). This complements the annotations well. Could mention whether behavior might change without notice, but the 'candidate routing improvements' phrasing implies that. Slightly stronger than just 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 compact and front-loaded. The first sentence establishes what it is (beta version of ask_pipeworx) with concrete specifics (5,581 tools, same arguments, same response shape). The second clarifies current state, the third gives usage guidance)Skip note about 'nothing'. It's efficient and every sentence adds value. Could arguably be slightly trimmed, but it's well-structured.

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

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

The tool is complex (5,581 tools, routing logic), and the description explains the beta status, identity with the stable version, and the comparison purpose. There's no output schema, but the description notes response shape is identical to ask_pipeworx, which covers that. The main gap is that it doesn't explain what the routing does or gives examples, but given the schema covers parameters fully, this is sufficient. A 4 seems right; could be 3 if we demand more, but the sibling context and existing tool knowledge fill 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 has 100% description coverage: all 6 parameters (question plus 5 aliases) have descriptions. The description reinforces that it uses the same arguments as ask_pipeworx, which adds confidence but doesn't repeat schema text. Given high coverage, the description doesn't need to add much, but it does contextualize the parameter set as identical to the sibling. Baseline 3 plus the extra contextual note earns 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 identifies the tool as the beta version of ask_pipeworx, a universal router covering 5,581 tools with the same arguments and response shape. It explicitly distinguishes it from the stable ask_pipeworx by noting it's the experimental edge with candidate routing improvements. The verb 'ask' and resource 'Pipeworx' are specific, and it differentiates itself from siblings by naming its stable counterpart.

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 guidance: 'Use it exactly like ask_pipeworx when you want the newest routing'. It explains the context (candidate routing under test), the current state (no candidate active, matches ask_pipeworx exactly), and the purpose (results compared against stable router for merge decisions). This is clear direction on when to select this tool over alternatives.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, and the description adds substantial context beyond that: exact success and refusal response shapes, the rule that answers are extracted only from tool results, common refusal reasons, and the cost of one extra LLM call. This gives the agent a clear model of how the tool behaves and when it will refuse.

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

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

The description is dense but every sentence earns its place: it states the core purpose, explains the mechanism, enumerates response shapes, enumerates refusal reasons, gives concrete use cases, and clarifies the cost tradeoff against the sibling. The most important differentiator is front-loaded.

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

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

Given the absence of an output schema, the description fully explains both the success and refusal response structures, including specific refusal_reason values. It also covers when to use the tool, when to prefer the sibling, routing behavior, and cost, making it self-sufficient for an agent to decide and invoke correctly.

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

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

The input schema already documents the question parameter and its aliases with 100% coverage, so the description does not need to add parameter-level detail. The description adds no new meaning about the parameters themselves beyond the tool-level behavior of filling arguments through routing, which is already explained at a high level.

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 this as a 'hallucination-resistant answer mode for high-stakes reads' that extracts answers using only tool results and returns explicit refusals. It distinguishes itself from sibling ask_pipeworx by emphasizing grounded extraction and refusal behavior, so an agent can tell them apart immediately.

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

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

The description gives explicit guidance: use 'whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains like financial verdicts, legal claims, medical lookups, and public statements. It also names the alternative ask_pipeworx for casual lookups and notes the extra LLM call cost, making the tradeoff 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 declare readOnly, idempotent, openWorld. The description goes far beyond that, detailing resolver confidence fields, low-confidence short-circuits, closed-market status behavior, GDELT fallback mechanics, wide-spread tradeability flags, and resolution-rule risk (cancellation_rule). It fully discloses edge cases and safety guardrails, with no contradiction to annotations.

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

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

The description is very long but well-structured with bolded section markers (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, SAFETY, RESOLUTION-RULE RISK) and front-loaded purpose. Most sentences carry unique information needed in the absence of an output schema, though a few technical digressions (e.g., 'audited arb-bot ledgers') could be trimmed without loss.

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 and the tool's high complexity (resolver, classifiers, parallel fan-out, multiple response shapes, statuses, fallbacks), the description is exceptionally thorough. It covers resolution trust, parent event extraction, news fallback handling, illiquidity warnings, safety short-circuits, and resolution-rule risks, leaving little unaddressed for an agent to invoke and interpret the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the market parameter with examples (slug, URL, question text) and fleshes out fan-out behavior, but it does not add semantic detail for the 'depth' or 'include_raw' parameters beyond what the schema already states. It neither improves nor degrades the schema's parameter explanations.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly explains what the tool does and distinguishes it from siblings like polymarket_arbitrage or polymarket_edges by emphasizing a comprehensive research + market-vs-model comparison role, with concrete 'Use for' queries.

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

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

Explicit usage guidance is given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' The fan-out examples illustrate contexts, but it does not explicitly name alternative sibling tools or state when NOT to use this tool, so it stops short of full exclusion-based guidance.

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

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

Annotations already declare readOnly/idempotent/destructive hints; the description adds rich behavioral detail: pulls from SEC EDGAR/XBRL for companies, FAERS for drugs, handles off-calendar fiscal years, sorts results by primary metric, and returns citation URIs. No contradiction.

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

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

The description is long but information-dense, with examples and clear structure. Every sentence adds value, though it could be slightly more scannable. It's not merely verbose; each detail 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?

Despite lacking an output schema, the description fully covers data sources, return format (paired data + URIs), sorting behavior, and edge cases like fiscal year handling. It gives the agent everything needed to invoke correctly.

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

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

The schema already covers both parameters with descriptions and enums, but the description adds substantial meaning: explains what each type pulls, provides concrete examples for values, and clarifies the 2–5 entity constraint. This goes well beyond the schema.

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

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

The description clearly states it performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with specific query patterns like 'X vs Y' and 'rank these companies'. It distinguishes itself from sequential lookups and sibling tools by emphasizing the batch comparison approach.

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

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

Explicitly specifies when to use: for comparison queries and ranking, and states 'ALWAYS PREFER over sequential single-pack lookups', providing a clear when-not and alternative. Though it doesn't name a specific sibling tool, it gives strong contextual 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?

The description is candid about latency ('15-60s', 'up to ~90s' with thorough), account requirements, and the fidelity-latency trade-off (80% context at 80% latency/accuracy etc.). It also explains the `hop` field and the conditional citation URI. No contradiction with annotations (which are absent, so no issue). It goes beyond safety to operational expectations.

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

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

The description is long (~250 words) and front-loads account info before the core purpose. It packs a lot of detail (latency, fidelity, hop field) but could be more concise, separating critical routing information from operational details. Some sentences are dense but still relevant.

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

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

Given no output schema, the description explains return value structure (trails, hop field, citations) and conditions for fidelity. It covers what an agent needs: when to use, prerequisites, depth options, and expected output. It doesn't describe all sources, but that's not essential; the stated scope and constraints are adequate.

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

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

Schema coverage is 100% (question and depth are both described in the schema). The description adds nuance about what makes a good question (long-form, not coding) and detail on depth variants, which is useful. It does not add new parameter meaning beyond the schema, so baseline 3 is appropriate. The added trade-off numbers are extra but not strictly param semantics.

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 'multi-source research' with citations and research trails, distinguishing it from a simple search. It also positions it as the tool to use when grounded, citable research is needed, with an explicit pointer to ask_pipeworx for non-signed-in users. Some redundancy ('research... research') could be tightened, but the core purpose is 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 is explicit about account requirements (free vs. paid) and directs non-signed-in users to ask_pipeworx. It also differentiates depth levels and advises that it is best for long-form research questions, mentioning deep_web for other tasks. This is strong routing guidance that an agent can act on without extra 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context about the return format ('Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)') and states that results are 'ready to call directly, no second schema lookup needed.' This goes beyond what annotations provide.

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

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

The description is four sentences, front-loaded with the core purpose, then usage context, return behavior, and a strategic recommendation. Every sentence contributes unique information 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?

For a discovery tool with no output schema, the description adequately covers what it returns (top-N tools with schemas) and when to use it. It also covers the usage context with a list of domains. It doesn't explain the matching algorithm or default limit, but these are either in the schema or not essential for invocation. The description is sufficiently complete.

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

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

Schema coverage is 100% with clear descriptions for the required query parameter and the limit parameter, including aliases and defaults. The description's mention of 'top-N' and 'describing the data or task' aligns with the schema but doesn't add significant new semantic meaning. Given full schema coverage, 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 opens with 'Find tools by describing the data or task' which is a specific verb+resource statement. It clearly differentiates this tool from siblings by positioning it as a discovery meta-tool ('Call this FIRST when you have many tools available') and lists the domains it covers. This is a precise and unambiguous 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?

It explicitly states when to use the tool ('Use when you need to browse, search, look up, or discover what tools exist') and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' While it doesn't name an alternative tool directly, the context strongly implies the alternative is calling a specific tool directly. The guidance is clear and actionable.

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

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

Annotations declare readOnly and idempotent, and the description adds substantial behavioral context: fans out across multiple sources, returns specific fields, mentions the patents API soft-fail, and describes the GDELT→GNews fallback. This goes beyond the annotation hints 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 dense but well-structured: example queries lead into the purpose, then fan-out details, then parameter guidance. Each section serves a purpose; the examples are not waste because they directly illustrate accepted inputs. It is appropriately sized for the tool's complexity.

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

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

Since there is no output schema, the description does thorough work by enumerating all return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and caveats (patent soft-fail, news fallback, filing count cap). It also clarifies input constraints and the parallel-call nature, making the tool's behavior well-understood.

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 both parameters are fully described, including the note that names are unsupported. The description only adds example values (AAPL, 0000320193) and reinforces the schema text, providing little additional semantic meaning.

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 defines a specific action—'full cross-source profile of a US public company'—with concrete example queries. It distinguishes itself from sibling tools by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and names resolve_entity as an alternative for name-only inputs.

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

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

Explicitly states when to use: 'when the user asks for a holistic view.' It also provides clear guidance on input types ('Pass ticker or zero-padded CIK') and directs name-only lookups to resolve_entity, making the tool's place among siblings clear.

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

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

Annotations already declare readOnly=false, destructive=true, and idempotent=true, covering the safety profile. The description adds context about what is deleted (memory) and why, but does not disclose additional behavioral traits such as return behavior or error handling. It meets the lower bar with annotations but adds limited new behavioral information.

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 short sentences, each serving a distinct purpose: action, usage, and relationships. It is front-loaded with the core function and contains no redundant words.

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

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

Given the tool's simplicity (one parameter, no output schema, clear annotations), the description is sufficient. It covers what the tool does, when to use it, and related tools, making it contextually 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 single parameter 'key' has full schema coverage with a clear description. The tool description's mention of 'by key' merely reinforces the schema without adding new semantic detail, so the baseline 3 is appropriate.

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

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

The description clearly states the tool deletes a previously stored memory by key, using a specific verb and resource. It distinguishes the tool from siblings by the nature of deletion, and the mention of pairing with remember and recall clarifies its complementary role.

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

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

The description explicitly provides use cases: stale context, completed task, or clearing sensitive data. It also names related tools (remember and recall) as pairs, offering clear context on when this tool fits relative to alternatives.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds process details: fetches the page, extracts specific elements, outputs a single text blob in standard llms.txt format. This goes beyond annotations without contradiction.

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

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

Three sentences effectively convey purpose, process, and use cases. All content is relevant, though the use case list could be slightly condensed without loss.

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 full schema coverage and solid annotations, the description fully covers purpose, behavior, output format, and usage scenarios. No critical information is missing.

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

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

Schema coverage is 100%, with descriptions for url and max_links. The tool description does not provide additional parameter-specific guidance; both parameters are adequately documented in the schema itself.

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: generating a production-ready llms.txt file for any URL. It specifies the process (fetches page, extracts title/description/key links, emits markdown) and distinguishes from siblings by focusing on file generation rather than presence scanning or 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?

Lists specific use cases: getting a client's site indexed, drafting for own project, or auditing competitor visibility. This provides clear context for when to use the tool, though it does not explicitly name alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not repeat safety. It adds value by detailing the exact schema components returned (fields, geometry type, count, capabilities), which is useful behavioral context beyond annotations.

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

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

The description is one concise sentence, front-loaded with the core action and resource, then lists the returned components efficiently. No filler or redundant wording.

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 simplicity of the tool (one parameter, no output schema, safe annotations), the description fully communicates what the tool does and what it returns. It is complete for the user's decision-making needs.

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

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

The input schema covers the single 'url' parameter with 100% coverage, including an example and description. The tool description adds nothing beyond the schema for parameter meaning, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Get') and clearly identifies the resource (ArcGIS Feature/Map Service layer schema) along with the exact data returned (fields, geometry type, count, capabilities). This distinguishes it from sibling tools like query_layer, which would fetch data rather than schema.

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

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

The description clearly implies when to use the tool: whenever a layer's schema is needed from a URL. It does not explicitly mention alternatives or when-not-to-use, but the purpose is so specific that usage context is clear. No exclusions are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond annotations: it clarifies that the tool operates on the caller's subscriptions, defaults to active only, and returns specific fields. This is helpful behavioral disclosure, though not extensive.

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, then return fields, then usage context. Every word earns its place. No redundancy or fluff.

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

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

For a simple read-only tool with one optional parameter and complete annotations, the description fully covers the what, the return shape, and the when. The lack of an output schema is mitigated by listing return fields. No critical information 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?

The schema covers the only parameter (include_inactive) with a clear description and default. The tool description does not add additional meaning beyond the schema, so baseline 3 applies. No gaps to compensate for.

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 'List' and clearly identifies the resource: 'the caller's active subscriptions.' It distinguishes from sibling tools like subscribe/unsubscribe by focusing on reviewing existing subscriptions. It also lists the returned fields, making the purpose explicit and unambiguous.

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

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

The description provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly tells the agent when to use this tool relative to subscribe/unsubscribe, and implies alternatives. It's clear and actionable.

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

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

Beyond the annotation set (which only says not read-only, not idempotent, etc.), the description discloses the claim_token lookup mechanism, daily rate limit of 5, that it's free/quota-free, and that the team reads digests daily. These are substantive behavioral traits not visible 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 front-loaded with the primary purpose, then logically flows through use cases, exclusions, claim token behavior, and limitations. Every sentence carries operational or policy-relevant information; no filler or repetition of schema details.

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

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

Despite having no output schema, the description explains what filing returns (a claim_token), how to use it, rate limits, and scope boundaries. It fully covers the tool's context, making it self-sufficient for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description adds value by advising users to describe issues in terms of Pipeworx tools/packs and not paste the end-user's prompt, and by demonstrating the claim_token round-trip call. This goes beyond the schema baseline of 3.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the four feedback types (bug, feature/data_gap, praise), which clearly distinguishes this from sibling tools like ask_pipeworx or discover_tools—none of which are about submitting feedback.

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

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

Explicit 'Use when' conditions cover bug/stale data, feature/data_gap, and praise. It also states a firm exclusion: only for tools served by this Pipeworx connection, with an alternative action (file with that server) for other MCP servers. This is exemplary usage guidance.

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

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

Adds valuable behavioral context beyond annotations: caching (5min-1h), data source (CF analytics-engine), and privacy (no PII). This is exactly the kind of disclosure agents need for trust and repeatability.

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

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

Front-loaded with the core purpose in the first sentence, then logically organized into return value, use cases, and operational details. Every sentence adds value—no filler or redundancy.

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

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

Given the tool's simplicity (1 optional param, strong annotations, no output schema), the description fully covers return values, use cases, caching, and privacy. It is complete enough for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% and includes full semantics for the 'window' parameter. The description only restates the same window options without adding any new meaning, so baseline 3 is appropriate.

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

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

The description clearly states the tool 'Returns the top tools, top packs, and total call volume over a recent window', with a specific verb and resource. It distinguishes itself from siblings like discover_tools by focusing on what other agents are calling on Pipeworx right now.

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?

Three explicit use cases are provided: discovering hot data sources, confirming canonical tool choice, and aligning with agent needs. However, it does not explicitly state when not to use it or name alternative tools, so it's clear but lacks exclusions.

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

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

Although annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, the description adds substantial behavioral context: it details the partition_check logic, placeholder filtering, Jaccard similarity threshold, and crucially the fill check that advises not to trade when realizable edge is ≤0. This goes far beyond the structured annotations.

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

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

The description is long but densely packed with useful information, structured into logical sections (modes, semantic anchor, partition filter, response, fill check). It is front-loaded with the primary purpose, and while it could potentially be formatted with bullets, every sentence earns its place for such a complex tool.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: it outlines the structure of opportunities[], partition_check fields, and the fill check result semantics. It also covers edge cases like placeholder filtering and low similarity, making the tool's behavior comprehensible without external references.

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 both parameters with descriptions, but the tool description adds significant semantics: it provides concrete example values (e.g., 'fed-decision-may-2026'), explains the behavior difference between event and topic modes, and elaborates on output structure. This adds meaning well beyond the schema descriptions.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes between the three invocation modes (trending_scan, event, topic) and references a sibling tool (polymarket_fill_risk) for custom sizing, making its purpose unmistakable.

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

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

Explicit when-to-use guidance is provided: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends which mode to use for specific scenarios and explains when cross-event mode is preferable, including a pointer to a sibling tool 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?

The description goes far beyond the readOnly/idempotent annotations by explaining the exact computation models, filtering rules (e.g., placeholder-slug filter, >20% placeholder fraction skipped), the per-leg favorite-longshot bias correction, the 24h-move warning, and the KV-level 1h caching. It also discloses that partition arbs always return kelly_fraction_half=0 and explains the implications. This provides deep behavioral transparency without contradicting the annotations.

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

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

The description is a single dense paragraph of roughly 350 words, which is not concise. While every sentence adds technical detail, the length and lack of structural breaks (e.g., bullets) make it harder for an agent to quickly parse the key facts. The main purpose is front-loaded, but the overall size is excessive for a tool description.

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

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

With no output schema, the description fully explains the response structure: top-level by_segment with three segments, fed_candidates/fed_note, and _diagnostics with funnel counters. It also explains each segment's model composition and the tradeable-edge knobs. For a tool of this 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?

Although the schema already covers all nine parameters, the description adds cross-parameter semantics: it groups min_liquidity and max_spread_pp as 'TRADEABLE-EDGE KNOBS' that drop unrealizable edges, and explains that min_partition_leg_kelly applies per-leg rather than parent level because partition arbs return 0 parent Kelly. It also clarifies that slippage_pp is subtracted before ranking. This goes beyond the schema's per-parameter descriptions.

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

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

The description specifies a clear action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes the tool from siblings by detailing three unique model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and the 'what should I bet on today' use case, which is not seen in sibling names.

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 context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' This clearly indicates when to use it. It also notes that 'Fed bets surface here, excluded from ranking' and that callers can see why segments are empty, giving operational guidance. However, it does not explicitly name alternative sibling tools or state when not to use the tool, so it falls short of a 5.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior, but the description adds substantial operational details: snapshots are written on cache-miss (so gaps mean no scan), history is bounded by a 60-day TTL, decay is computed from daily closes rather than intraday, and expired opportunities include lifespan. This goes far beyond the annotation baseline.

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 long, but nearly every sentence adds value. It front-loads the core purpose, then uses RESPONSE and LIMITS sections to organize return semantics and caveats. A bit more formatting would improve readability, but the structure is serviceable given the information density.

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 structure (tracked, expired, snapshot_dates), explaining trend categories, decay calculation, lifespan interpretation, snapshot gap semantics, and historical limits. This is thorough for a moderately complex telemetry 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% and already describes both parameters (days lookback with default/clamp, window family with default). The description repeats this information nearly verbatim, so it adds little beyond what the schema provides. It does clarify that window selects a 'snapshot family', but this is also present in the schema's phrasing.

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

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

The description clearly states this tool provides 'edge persistence and decay telemetry' built from daily snapshots, with a specific question it answers ('how long has this edge existed and is it shrinking?'). It distinguishes itself from siblings like polymarket_edges by focusing on historical persistence and decay rather than current edge values.

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

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

The description gives strong contextual guidance, explaining that a fresh wide edge and a 3-week-old wide edge are different trades, implying this tool is for assessing edge age and decay. It does not explicitly name alternatives like polymarket_edges for current edges, but the contrast is implicit and clear enough for an agent.

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

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

The description goes beyond the annotations (readOnly, openWorld, idempotent, not destructive) by detailing what the tool computes and returns: 'walks the ladder and returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict.' It also discloses risk insights like 'forced_directional_risk naming the legs most likely to strand you unhedged' and warns about partial fills. This is rich behavioral transparency that adds context not captured in the structured metadata.

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

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

The description is long but every sentence earns its place. It is front-loaded with the core purpose, then structured into clear SINGLE-MARKET and BASKET sections with parallel structure, and ends with a compelling 'USE THIS' guidance. The length is justified by the tool's complexity and the critical risk information it conveys. No redundant filler or tautology.

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 the return values for both modes: 'returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict' and 'returns theoretical_sum vs realizable_sum ... capture_ratio, profit_usd ... thin_legs[], max_clean_notional_usd.' It covers both modes, parameter defaults, risk warnings, and the exact use case. Given the complexity, this is as complete as a description can be without an output schema.

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

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

Although the schema already describes all four parameters, the description adds significant semantic nuance. For example, it explains 'size_usd' has different meanings in single-market vs basket mode: 'max spend on buys, target proceeds on sells' vs 'settlement notional S (shares per leg; each share pays $1)'. It also clarifies default behavior for 'side' in basket mode: 'default auto from partition sum.' This added value goes well beyond the schema descriptions, justifying a high 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 opens with a specific, informative statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes single-market and basket modes, and explicitly names sibling tools (polymarket_arbitrage, polymarket_edges) to position its unique role. This goes far beyond a vague purpose and clearly differentiates from 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?

Usage guidance is explicit and actionable: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' The description also explains why this tool is necessary ('theoretical overround on thin books is not capturable') and the risk of not using it ('partial basket fills convert an arb into an unhedged directional position'). This is ideal when-to-use guidance with reasoning.

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 extensive behavioral detail beyond that: compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type counters, and the warning that pre-mapped ≠ tradeable. This fully discloses edge cases and failure modes.

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

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

The description is long but uses clear structure: TWO MODES, RESPONSE, SAFETY FIELDS. Every sentence carries substantive information. It is not bloated with fluff, though it could be considered dense. The format helps an agent parse the key details efficiently.

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: leg-by-leg prices, matched spread[].top_spreads_pp, compatibility_warning cases, and temporal_alignment. It also covers edge cases (skipped_cross_type). The description is thorough for a tool of this complexity.

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

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

Schema coverage is 100% and each parameter has a description. The description adds value by explaining the topic shortcut list, how explicit tickers override topic-mapped sides, and the distinction between the two modes. It goes beyond the schema's basic field descriptions.

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

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

The description opens with a precise statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This names the specific resource (two prediction markets) and the action (calculating spread), clearly distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edges. The two modes (topic and explicit tickers) further clarify 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 explains when to use each mode: 'topic' for 10 pre-mapped shortcuts, and explicit tickers for custom pairings. It warns that most pre-mapped topics return compatibility_warning, so users know not to expect tradeable spreads. It does not explicitly name alternatives, but the clear mode differentiation and caveats provide strong usage context.

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

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

Annotations already declare readOnlyHint: true, destructiveHint: false, and idempotentHint: true, so the agent knows this is a safe read operation. The description adds valuable behavioral context by stating the return format ('Returns attribute rows (and geometry)') and a sampling approach. No contradictions with annotations. This adds meaningful context beyond structured fields.

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

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

The description is two sentences, front-loaded with the core purpose, and includes a useful example/sampling tip. Every word earns its place; no redundancy or fluff.

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

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

For a read-only query tool with 6 parameters (all documented in schema) and no output schema, the description adequately covers purpose, usage, and return format. It mentions the integration with search_datasets, the return of rows and geometry, and a sampling pattern. This is complete for an 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?

Schema coverage is 100% with each parameter already described (url, limit, where, offset, order_by, out_fields). The description restates these parameters in a grouped, SQL-like manner but adds no new meaning beyond the schema, except for the operational tip. Since schema does the heavy lifting, the baseline 3 is correct.

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: 'Query an ArcGIS Feature Service / Map Service layer by its url'. It specifies the resource type (ArcGIS layer), the action (query), and distinguishes itself from siblings by referencing search_datasets as the source of the URL. This is a specific verb+resource+scope definition.

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 clear prerequisite ('by its url (from search_datasets)') and a concrete usage tip ('Use where="1=1" + out_fields="*" to sample'). It implies when to use the tool but does not explicitly mention alternatives or when not to use it. This is clear context with no exclusions, so a 4 is appropriate.

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

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

The description adds valuable context beyond annotations: the scoping mechanism (anonymous IP, BYO key hash, or account ID) and the omit-key behavior for listing all keys. It is consistent with the readOnlyHint, idempotentHint, and destructiveHint 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 concise sentences: the first states the core function, the second provides use-case context, and the third covers scoping and pairing with siblings. Every sentence contributes genuine information without waste.

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

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

For a tool with a single optional parameter, no output schema, and strong annotations, the description adequately covers behavior, scoping, and relationship to sibling tools. It leaves no critical gaps for an 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?

Schema description coverage is 100%—the 'key' parameter is fully documented with 'Memory key to retrieve (omit to list all keys)'. The description does not add extra semantics beyond the schema's own description, so the baseline of 3 applies.

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

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

The description clearly states the tool retrieves a saved value or lists all saved keys when the key argument is omitted. It distinguishes itself from siblings 'remember' (save) and 'forget' (delete) by explicitly naming them and describing the complementary lifecycle.

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 advises using the tool to look up context the agent stored earlier, with concrete examples like tickers and addresses, and explicitly pairs it with 'remember' and 'forget'. It does not provide an explicit 'when not to use' statement, but the context is clear.

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

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

Annotations already declare read-only and idempotent hints, but the description adds the crucial conditional side effect of mark_read:true (flags events read and advances the feed) and details the return structure (source, citation_uri, raw event). No contradiction is present; the optional side effect is disclosed transparently.

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

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

The description is four sentences, front-loaded with the core action, and every sentence adds valuable information: return payload, filtering, mark_read behavior, and the external URL alternative. 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 read/list tool with no output schema, it thoroughly explains return values, filtering, optional side effects, and polling behavior. Parameters like unread_only and limit are sufficiently specified in the schema. It is complete for an agent to use effectively.

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 alone documents all 5 parameters. The description only provides illustrative examples (type 'sec_8k', since ISO timestamp, mark_read:true), without adding substantive semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly distinguishes this from siblings like list_subscriptions (which lists subscriptions) and recent_changes (which tracks changes). The return payload is also outlined, 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 provides clear context with 'Polls work fine' and offers an explicit alternative: 'the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' It does not explicitly exclude sibling tools, but this is sufficient to guide an agent on when to use this tool interactively.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral context: it fans out to SEC EDGAR, GDELT→GNews with a fallback mechanism, and USPTO with a soft-fail due to API sunset. It also discloses the return structure and citation URIs. This is genuinely additive and consistent 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 logically ordered and each sentence adds value, but the initial list of example queries ('What's new with X' / 'latest on Y' / ...) is slightly redundant and could be condensed. It remains well-structured and front-loaded with purpose, earning a 4.

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

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

Despite lacking an output schema, the description explains the return shape (changes[] grouped by source, total_changes count, citation URIs) and external dependencies (SEC, GDELT, GNews, USPTO) with failure modes. For a multi-source aggregation tool, this is thorough enough for an agent to invoke correctly.

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

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

The input schema provides 100% coverage for all three parameters, including detailed descriptions and examples for `since`. The description repeats the format examples but does not add new parameter-level meaning beyond what the schema already offers, so the baseline score of 3 applies.

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

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

The description clearly identifies the tool as a change feed for a company over a time window, with natural-language intents at the start ('What's new with X'). It explicitly distinguishes from the sibling tool entity_profile, which provides static profiles, making the purpose specific and differentiated.

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

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

The description gives concrete usage scenarios ('latest on Y', 'updates on Acme') and explicitly names an alternative (entity_profile) with a clear rule for choosing between them ('Use entity_profile instead when you want the static profile'). This provides actionable guidance on when to use this tool versus alternatives.

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

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

Beyond the annotations, the description adds valuable behavioral context: key-value storage scoped by identifier, persistent memory for authenticated users, and 24-hour retention for anonymous sessions. This is consistent with idempotentHint and adds details not present in the 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?

Three sentences, front-loaded with the main purpose, and each sentence contributes distinct value (what, when, storage details, related tools). 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 two-parameter memo tool with no output schema, the description covers all necessary context: purpose, usage triggers, scoping, persistence, and sibling relationships. It is fully adequate for an agent to invoke correctly.

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

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

The input schema already provides 100% coverage with clear descriptions and examples for both key and value. The description adds no additional parameter-specific 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 clearly states the tool's purpose with the specific verb 'Save' and defines the resource (data to reuse later). It distinguishes itself from sibling tools recall and forget by explicitly mentioning them for related operations.

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

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

Provides explicit guidance on when to use the tool ('Use when you discover something worth carrying forward') and directly names alternatives ('Pair with recall to retrieve later, forget to delete'), offering clear context on 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 declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description goes far beyond by detailing internal cascading through multiple lookup endpoints, graceful degradation (if GLEIF/OpenFIGI unavailable, EDGAR still returns), source labeling for each identifier, and explicit `unresolved` field for identifiers that could not be resolved. This level of behavioral detail is exceptional.

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 examples and the 'Use FIRST' directive. It is comprehensive but slightly verbose, especially the long parenthetical on company type. However, every sentence adds value for a complex tool with two distinct entity types. It earns a high score for structure, losing one point for unnecessary wordiness.

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 thoroughly explains what each entity type returns (CIK, ticker, LEI, FIGI for company; RxCUI, ingredient, brand for drug), how identifiers are labelled with sources, the `unresolved` field, and graceful degradation. This gives the agent a complete mental model of the tool's behavior and return structure. It is fully adequate for correct 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 coverage is 100%, so baseline is 3. The description adds significant meaning: for 'company' type it explains that inputs can include ISIN (beyond schema's ticker/CIK/name) and describes the ISIN-to-LEI mapping for non-US issuers. For 'drug' type it adds the RxNorm pipeworx citation. These details enrich understanding beyond the schema's enum and short descriptions.

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

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

The description opens with concrete query examples ('What's the ticker for…' / 'find the CIK for…') and clearly states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' The verb (resolve) and resource (name → identifiers) are explicit. It distinguishes from siblings like entity_profile by positioning itself as the tool used first when you have a name but 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 an explicit directive: 'Use FIRST whenever you have a name but need an ID.' This tells the agent when to use this tool and implies that other tools (like entity_profile) should be used afterward with the obtained IDs. It also contrasts with manual multi-tool lookups, stating the tool replaces 2-3 lookups. No explicit when-not-to-use, but the 'FIRST' guidance is strong enough.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral detail: probes each entity via ai_visibility_check, ranks results, and returns score/confidence/signal density. This goes beyond the schema and provides accurate expectations about the tool's internal behavior.

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

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

The description is two sentences, front-loaded with the core purpose, then adds a concrete use case and output summary. Every sentence serves a distinct purpose with no redundancy.

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

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

With no output schema, the description explicitly states the return format ('ranked list with score, confidence, signal density per entity'). It also covers the tool's scope (multi-entity, competitive audits). It doesn't mention model selection, but that is fully documented in the schema, so the description is sufficiently complete.

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

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

Schema description coverage is 100%, with all parameters documented. The tool description adds contextual framing ('your brand + N competitors', 'First entry treated as subject') but does not significantly augment the parameter semantics beyond what schema already provides. Baseline 3 is appropriate.

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

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

The description clearly identifies the action ('Compare AI visibility'), the resource ('multiple entities side-by-side'), and the differentiator from sibling tools ('your brand + N competitors', 'ranks by score'). This distinguishes it from the single-entity ai_visibility_check and the generic compare_entities.

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

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

It explicitly states the use case ('competitive AI-marketing audits') and provides a concrete example question ('does Claude know about us as well as our competitors?'). It also implies that ai_visibility_check is the lower-level tool by mentioning it as the probing mechanism, though it does not explicitly say when not to use this tool versus generic compare_entities.

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

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

Adds substantial behavioral context beyond annotations: mentions partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts while the rest still returns. The description does not contradict annotations.

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

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

The description is detailed but each sentence serves a purpose: purpose, data sources, usage triggers, return summary, ecosystem scope, and failure behavior. It is somewhat long but structured logically and not redundant. Minor trimming possible but well-organized.

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

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

For a composite tool with no output schema, the description fully explains what is returned (summary block fields, per-advisory detail, links, alternative versions) and covers limitations (NPM only) and edge cases (timeouts). It is complete enough for an agent to know what to expect.

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

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

Schema coverage is 100% with both parameters already described. The tool description adds no new parameter-specific meaning beyond what the schema provides; it only reinforces that 'package' is an npm package name, which is already in 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 performs a composite npm package evaluation check, combining deps.dev and bundlephobia data. It explicitly mentions the resource (npm package) and the verb ('check'), and distinguishes itself from siblings by covering multiple aspects (license, advisories, bundle size) in one call.

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 triggers: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also gives clear exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', directing users to alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read-only operation. The description adds valuable behavioral context by specifying the exact return fields (name, summary, record_count, owner/org, url) and that the url is intended for further use. 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 two sentences long, front-loaded with the core purpose, and every sentence adds value. The first sentence states what the tool does; the second lists return fields and downstream usage. No wasted words.

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

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

The tool has no output schema, so the description must explain return values, which it does thoroughly (name, summary, record_count, owner/org, url). It also covers the discovery-to-query workflow, making it complete for a read-only search tool with fully documented optional parameters.

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 itself does not add meaning beyond the schema: it references 'keyword' (query) but does not elaborate on limit or org_id. The schema already documents all three parameters adequately.

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

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

The description clearly states a specific verb ('Search'), a specific resource ('City of Aurora GIS open geospatial datasets'), and the scope ('by keyword'). It also lists the return fields, distinguishing it from sibling tools like query_layer and layer_info, which operate on a specific dataset URL rather than discovering datasets.

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

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

The description gives clear context for when to use the tool: to search and discover datasets by keyword. It provides a concrete downstream workflow by instructing to pass the returned Feature Service url to query_layer or layer_info. However, it does not explicitly state when not to use this tool or compare it with alternative search tools, so it stops short of a full 5.

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

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

Discloses technical behavior beyond the readOnlyHint annotation: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation flag, and return of character offsets/similarity scores. Annotations already mark it safe/read-only; the description adds algorithmic and edge-case detail 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?

Five sentences with front-loaded purpose and logical flow: what it does, when to use, how it pairs, technical details. Each sentence earns its place, though the technical details add length; overall well-structured and not redundant.

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

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

Despite lacking an output schema, the description fully covers the return shape (passages, offsets, similarity scores), limits (200K chars, top-N), and usage tips. For a three-parameter search tool, this is comprehensive and leaves no ambiguity.

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

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

The schema descriptions already cover all three parameters at 100% coverage, including text length limit, query examples, and limit range. The description reinforces 'top-N' and gives concrete text examples (SEC 10-K), but adds no new parameter-level meaning beyond what the schema provides.

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

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

The description opens with 'Semantic search INSIDE a fetched record', a specific verb-resource pair that immediately differentiates it from sibling tools like ask_pipeworx or compare_entities. It explains the input (pulled text + query) and output (top-N passages with offsets and scores), making the purpose unmistakable.

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

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

Provides an explicit 'Use when the record is too big to cram into the prompt' condition and mentions pairing with ask_pipeworx_grounded, giving clear context for when to prefer this tool. It stops short of explicitly listing 'when not to use', but the guidance is unambiguous.

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

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

The description goes far beyond the provided annotations, adding concrete behavioral details: OAuth account requirement, always-on feed channel with pull methods, optional email/SMS/webhook delivery, SMS verification and 10/day cap, webhook signing secret returned once, HMAC verification process, and auto-disable after 10 consecutive failing runs. These traits are not inferable 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 a dense paragraph but is front-loaded with the core action and return value. Every piece of information (auth, types, delivery, failure behavior) is relevant, though the length and heavy semicolon use make it less skimmable than ideal. It earns a high score for efficiency but not a 5 due to the wall-of-text format.

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 states explicitly that it returns the new subscription id. It also covers all essential context: required auth, subscription types, parameter examples, delivery channels, verification steps, rate caps, and failure handling. This is a fully self-sufficient description for a tool with nested objects and 3 parameters.

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 provides rich examples for each type and delivery channel. The description reiterates some examples but does not add meaningful new semantics for the parameters themselves. It does add account-level context (OAuth requirement, feed always on) but that is not parameter-specific, so the value over the schema is marginal.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes the tool from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation of a subscription and its return value (new subscription id). No ambiguity remains about what the tool does.

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

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

The description gives clear context on when to use the tool: for proactive monitoring via live-data event streams. It explicitly states an exclusion ('anonymous + BYO cannot persist subscriptions') and prerequisites (Pipeworx OAuth account). However, it does not name alternative tools for scenarios like one-time lookups or existing subscription management, so it falls short of full when-not-to-use guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context: it returns category-bucketed example questions, includes exact tool+argument shapes, is drawn from a live catalog, and supports no-arg or topic-scoped calls. No contradiction found.

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 somewhat long but front-loaded with natural language queries that immediately signal intent. Every sentence contributes useful information (what it returns, how to call, when to use), so it is effective despite being verbose.

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

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

No output schema exists, but the description fully explains the response contents (category-bucketed questions with tool+argument shapes) and lists the categories. It also covers the parameter behavior and use-case context, making it complete for an agent with no additional structured data.

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 documents the 'topic' parameter with enum values and behavior. The description adds examples ('finance', 'pharma', 'betting') but no new semantic information beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. The verb 'suggest' and resource 'questions' are specific, and the description distinguishes it from siblings like discover_tools by focusing on what to ask.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to focus with an optional topic. This gives clear when-to-use guidance and implies it precedes other meta-tools, satisfying the usage guideline dimension.

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

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

The description goes beyond the annotations by disclosing that ownership is enforced ('you can only cancel your own subscriptions') and that the row is deactivated rather than deleted, preserving historical events in recent_alerts. This is valuable behavioral context that annotations alone do not 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 concise and front-loaded: the first sentence states the primary action, and the next two sentences add necessary behavioral details without any fluff. Every sentence earns its place.

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

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

For a simple one-parameter mutation tool with no output schema, the description covers the key aspects: what it does, the ownership constraint, the non-destructive effect, and the availability of historical events via recent_alerts. No significant gaps remain.

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

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

The input schema already provides full coverage of the single parameter with a clear description ('Subscription id (uuid) returned by subscribe'). The tool description does not add further parameter-level details, so the baseline of 3 for high schema coverage is appropriate.

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

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

The description clearly states the action: 'Cancel a subscription by id.' This is a specific verb+resource combination that uniquely identifies the tool's function and distinguishes it from sibling tools 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 provides clear context for use: it is for cancelling a subscription you own, and the effect is deactivation rather than deletion. However, it does not explicitly mention when not to use this tool or name alternative tools (e.g., list_subscriptions), missing the top tier for explicit when/when-not guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context beyond that: it reveals the two pipeline paths, the exact percent-delta math, the verdict set, and crucially distinguishes could_not_verify (check did not happen, must not be treated as evidence) from unsupported (no source exists). This is exactly the kind of failure-mode disclosure that helps the agent interpret results correctly.

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 trigger phrases and efficiently packed with actionable details: routing, verdict semantics, citation format, and error handling. Every sentence contributes useful information, and the importance callout about could_not_verify is placed near the end after the core behavior. It is not overly verbose for the complexity it covers.

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 enumerating all possible verdicts, the citation mechanism, reasoning output, and the verification_error field for could_not_verify. It also explains the fallback behavior for non-financial claims and the distinction between unsupported and could_not_verify. This makes the tool's behavior and return values clear enough for correct invocation and result interpretation.

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

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

The input schema already provides 100% coverage with detailed descriptions, including tolerance_pct semantics and examples. The tool description does not add significant parameter-specific meaning—only vague mention of 'exact percent-delta math.' Since the schema carries the load, the description provides no extra value, so baseline 3 is appropriate.

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

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

The description opens with natural-language trigger phrases and explicitly defines the tool as 'natural-language claim verification against authoritative sources.' It also distinguishes the tool by describing its two distinct routing paths (SEC EDGAR/XBRL for company financial claims and a grounded pipeline for all other factual claims), which clearly separates it from sibling tools like ask_pipeworx_grounded or deep_research.

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

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

The description states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing explicit when-to-use context. It further explains that it replaces 4–6 sequential calls, which clarifies the intended workflow. However, it does not explicitly name alternative tools or give when-not-to-use guidance, so it misses full exclusionary instructions.

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