Arcgis Lorain

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds meaningful behavioral detail: default model selection (Workers AI Llama-3.3-70b free), the BYO-key billing responsibility for Anthropic calls, and the exact return structure ({score, confidence, signals, raw_response} plus a combined view). 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 three sentences, front-loaded with the primary action and outcome, followed by default behavior, return format, and use cases. Every sentence provides necessary context without 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?

Given four parameters fully described in the schema, strong annotations, and no output schema, the description adequately covers return format, default behavior, and example use cases. It supplies enough information for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds operational semantics beyond the schema: the default model when 'models' is omitted, the dependency between 'models' and '_apiKey' (only needed for 'anthropic'), and the billing implication. This clarifies how to use the parameters correctly.

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

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

The description clearly states the tool's function with a specific verb ('probe') and resource ('LLMs'), and defines the measurable outcome ('score visibility 0-100 per model'). It distinguishes itself from sibling research tools by focusing on LLM knowledge about any entity, not just Pipeworx-specific data.

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

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

The description provides concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to include the optional Anthropic model ('pass _apiKey to also probe Anthropic'). It doesn't explicitly exclude alternatives but gives clear context for when this tool 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?

Annotations already provide readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is known. The description adds meaningful behavior beyond that: it routes to one of 5,596 tools, automatically fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. No contradictions; the remaining lack of details about rate limits or error handling is acceptable given the annotation safety coverage.

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

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

The description is long, but the extra length is functional: it starts with 'PREFER OVER WEB SEARCH' and immediately communicates broad scope, and the later sentences provide explicitly directional alternative usage. The list of examples and domains is fairly lengthy but reinforces the agent's routing decision. Each major section earns its place, though some trimming would be possible.

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

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

There is no output schema, so the description should clarify what the agent can expect; it does, by stating that the return is a structured answer with stable pipeworx:// citation URIs. It also gives enough context around 'current and historical data' and 'authoritative structured data' for the typical use case. It does not cover every error scenario or rate-limit, but for a general-purpose routing tool of this breadth, the coverage is solid.

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 schemas already describe all six parameters at 100% coverage, including the 'question' property and alias identification. The description adds context that the user can write natural-language questions and the tool fills documented arguments automatically, but that's not substantially new parameter semantics. The schema handles the parameter explanation, so a 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 routes natural-language questions to thousands of domain-specific tools and returns structured answers with stable citation URIs. It names the resource, the verbs ('routes', 'fills arguments', 'returns'), and explicitly declares itself the default starting point for most factual questions. It also distinguishes itself from siblings like ask_pipeworx_grounded, deep_research, and resolve_entity.

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

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

The description includes explicit PREFER/WEB SEARCH guidance, a long list of applicable question types ('what is', 'find', 'get the latest'), and concrete examples. It names alternatives for distinct scenarios: ask_pipeworx_grounded for citation-heavy answers, deep_research for multi-session reports, and resolve_entity for entity ambiguity. This is exactly the kind of when-to-use vs. alternative guidance an agent needs.

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

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

The description goes well beyond the annotations, disclosing the experimental nature, that candidate routing changes are enabled only while under test, that no candidate is currently active, that it currently matches ask_pipe effectively exactly, and that it 'falls back to nothing — this IS a full working router,' so the agent knows the tool won't silently no-op. This is rich behavioral context for a beta tool.

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

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

The most important distinction (beta + currently identical to stable) is front-loaded. Each subsequent sentence earns its place by clarifying the experimental on/off state, the comparison purpose, and the fallback guarantee. Slightly dense, and the 'latest retired on 2026-07-26' detail may age, but it's very informative and no sentence is 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 beta variant that behaves identically to its stable sibling, the description covers everything an agent needs: current behavior parity, when behavior diverges, the input shape being shared, and the guarantee that it is a fully operational router. There is no output schema needed because the response shape is explicitly stated to be identical to ask_pipeworx. It does depend on the agent understanding what ask_pipeworx does, but it points to that sibling explicitly.

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% — each parameter documents that it's an alias of the required 'question' parameter, and the description adds no additional parameter detail. The baseline of 3 applies because the schema carries the full semantic load; the description merely says 'same arguments as ask_pipeworx,' which adds nothing 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 states a specific resource ('beta version of ask_pipeworx… identical universal router') and distinguishes it from the stable sibling via the 'newest routing' behavior. It doesn't spell out the core action of what a router does (returns an answer resolved across 5,596 tools, response shape) — it delegates that understanding to ask_pipeworx — so it's clear but slightly indirect.

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

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

Explicit guidance exists: 'Use it exactly like ask_pipeworx when you want the newest routing.' It names the alternative (ask_pipeworx) and the condition that selects this tool. It doesn't explicitly state when NOT to use it (e.g., 'for guaranteed stability use the stable router'), but the condition is sufficiently implied.

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 strongly complements the annotations by disclosing the refusal-reason mechanism, the exact return shape, and the grounded extraction strategy. It also clarifies the additional cost and non-inventiveness behavior, which annotations alone do not convey. No contradiction exists: readOnlyHint aligns with the extract-only 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 concisely packed into a few sentences without redundancy. Each sentence contributes a distinct element: behavioral guarantee, routing mechanics, return format, usage guidance, and trade-off against ask_pipeworx.

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 that there is no output schema, the description supplies essential structural information about the response and refusal reasons. It complements the annotations with use-case targeting, cost awareness, and a sibling alternative, making it complete enough for correct tool selection and invocation.

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

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

Schema description coverage is 100%, so the parameter 'question' and its aliases are already fully documented. The description adds no extra parameter-level guidance, but no compensation is needed because the schema carries the burden effectively.

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

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

The description clearly identifies this as the hallucination-resistant answer mode for high-stakes reads, distinct from ask_pipeworx and ask_pipeworx_beta. It names the specific behavior of extracting answers only from tool results and deliberately contrasts itself with the normal ask_pipeworx sibling.

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: whenever an answer will be quoted, cited, or acted on and facts must not be invented. It also provides a direct alternative and trade-off, recommending ask_pipeworx for casual lookups due to the extra LLM call cost.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses extensive behavioral context: resolver contract with match confidence scores, safety short-circuiting with 'low_confidence_match', 'market_closed_or_inactive' status, wide-spread illiquidity notes, and cancellation-rule risk parser. It also explains fallback behavior for news sources. This far exceeds what annotations provide and helps agents anticipate non-obvious outcomes.

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 exceptionally well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Each section is dense with actionable information and the structure makes it scannable. Front-loaded with purpose and usage, then diving into technical contract details. Every sentence adds value 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?

For a complex research tool with no output schema, the description is remarkably complete. It covers input types, output shapes (market, analysis, evidence), resolver matching convenance, parent-event handling, news fallback mechanics, safety statuses, and cancellation-rule edge cases. It also includes examples and warnings about 'phantom matches'. This fully equips an agent to use the tool correctly and interpret results safely.

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

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

The input schema already covers parameters with 100% description coverage. The tool description adds meaningful context beyond the schema: it explains market slug/URL/question-text resolution, depth choices with default 'thorough', and include_raw's impact on response size and use cases. While the schema is already good, the description enriches understanding with concrete fan-out examples and trade-offs, so it earns above baseline.

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

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

The description begins with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling tools (e.g., polymarket_edges, arbitrage) by focusing on a single bet, and it gives explicit input examples. The purpose is unmistakable and well-scoped.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains classifier categories and fan-out examples, giving concrete scenarios. The tool also details parameter choices (depth, include_raw) and edge-case blocking paths, making when-to-use very clear.

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

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

The annotations already declare readOnly, idempotent, and non-destructive, and the description adds substantial context: it lists specific SEC EDGAR/XBRL fields for companies, FAERS data for drugs, sorting by primary metric, citation URIs, and handles off-calendar fiscal years correctly. This is valuable behavioral disclosure 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 compact and front-loaded with natural-language query triggers, then states the preference rule, then per-type data details. Every sentence earns its place—there is no filler, and it remains readable despite its length.

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

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

With no output schema, the description sufficiently explains return value structure ('paired data + pipeworx:// citation URIs'), sorting behavior, and the parallel-execution advantage. It fully covers the 2-parameter interface and the tool's role relative to siblings, making it complete for an agent.

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

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

Schema coverage is 100% (both parameters have descriptions, enum for type). The description adds meaning by explaining what each type actually returns (revenue/net income for companies; adverse-event/trial counts for drugs) and implicitly confirms the values array maps to tickers/CIKs or drug names. This enriches the schema without redundancy.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, using specific verbs and resource scope. It distinguishes from siblings by explicitly saying 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' which names the alternative pattern.

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 when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and 'Replaces 8–15 sequential lookups.' It also clarifies the company vs drug data sources, helping the agent decide which type to choose.

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 readOnly/idempotent/openWorld, and the description adds substantial behavioral disclosure: execution via parallel decomposition into 5,596 tools, the exact findings packet structure (evidence, confidence, source, fetched_at, pipeworx:// citation), gap reporting, contradiction scan, semantic excerpting, and latency expectations. There is no contradiction with any annotation.

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

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

The description is well-organized and front-loaded with the most critical information (prerequisite and alternative), but it is somewhat verbose and repeats the ask_pipeworx alternative at multiple points. Every sentence mostly earns its place, yet tightening would improve readability without losing coverage.

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

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

The description covers every aspect an agent needs to correctly invoke the tool: account/pricing constraints, input expectations, execution duration, output shape, and behavior for unanswerable facets. Since there is no output schema, the explicit findings-packet description is crucial and fully provided.

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

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

The schema covers the parameters well (100% coverage), but the description adds practical context by elaborating the 'depth' semantics (quick/standard/thorough) and clarifying what 'question' should contain ('broad/multi-part is fine') and when not to use it (single lookups). This goes beyond the schema without replacing its 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 clearly states the tool's purpose: 'grounded multi-source research across Pipeworx's 1465 STRUCTURED data sources' in one call, and explicitly contrasts it with open-web search and single-lookup tools. It names a specific verb/resource, distinguishes it from ask_pipeworx, and gives concrete question examples defining the expected use case.

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

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

Explicitly states when to use this tool vs. when not: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead.' It provides a direct alternative, addresses the paid tier constraint for 'thorough' depth, and emphasizes that this tool is best for broad/multi-part questions over structured data.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description builds on this by disclosing return value behavior: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas... no second schema lookup needed.' This adds useful context about efficiency and output format beyond the annotations.

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

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

The description is four sentences, front-loaded with the core purpose, and every sentence earns its place. The domain list is lengthy but provides useful context for an agent deciding relevance. 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 description covers purpose, when to use, return format, and timing. Given the tool's simplicity and the rich annotations, it is fairly complete. A minor gap is that it doesn't explicitly state what 'tool' means here, but the context makes it clear. Overall adequate.

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

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

Schema description coverage is 100%, so each parameter (query, limit, aliases) is already documented. The description adds no additional parameter-specific meaning, just reaffirms that the query is a natural language description. Baseline 3 is appropriate when the schema handles the heavy lifting.

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

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

The description explicitly states 'Find tools by describing the data or task,' which is a clear verb+resource pairing. It distinguishes from siblings by framing this as tool discovery rather than data querying, and the enumerated domains (SEC filings, FDA drugs, etc.) give concrete 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?

It clearly says 'Use when you need to browse, search, look up, or discover what tools exist' and advises 'Call this FIRST when you have many tools available.' While it doesn't name alternative tools explicitly, the guidance provides strong context on when to invoke this vs. other tools.

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

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

Annotations already signal read-only, idempotent, open-world, and non-destructive behavior. The description adds substantial behavioral context: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, GDELT→GNews fallback, GLEIF), notes the USPTO API sunset soft-fail behavior, and details the specific return fields. 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 a single dense paragraph that front-loads example queries and the core purpose. It contains a lot of useful detail, but the structure could be improved with line breaks or bullet lists for the return fields and conditions. Still, every sentence contributes meaningful information without redundancy.

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

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

Despite the absence of an output schema, the description thoroughly explains what the tool returns (CIK/company name, recent filings with URIs, latest 10-K fundamentals sorted by period, patents with sunset caveat, news with fallback, LEI). It also covers input constraints and the fallback path, making the tool's behavior understandable in context.

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

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

Schema coverage is 100% with clear descriptions for both 'type' (enum, only company supported) and 'value' (ticker or zero-padded CIK, names not supported). The description largely repeats the same information with examples, adding little semantic value beyond what the schema already provides.

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

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

The description clearly states the tool's function: producing a full cross-source profile of a US public company in one call. It opens with natural language examples, names the resource ('US public company'), and explicitly contrasts itself with 'chaining single-pack SEC/XBRL/news lookups,' while also pointing to resolve_entity 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?

Usage guidance is explicit: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states that tickers or zero-padded CIKs are required, and names are not supported—directing users to resolve_entity first. This provides clear when-to-use and alternative 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, covering the safety profile. The description adds useful context about what is deleted (previously stored memory) and the motivation (clearing sensitive data), 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 two sentences long, immediately states the core action, and uses the second sentence for when-to-use guidance. Every word serves a 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?

For a simple one-parameter delete tool with strong annotations, the description covers purpose, usage, and context. It mentions related tools, and since no output schema exists, the description need not detail return values. An agent can select and invoke it correctly.

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

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

The schema description coverage is 100% because the single parameter 'key' is fully described as 'Memory key to delete.' The description adds no extra meaning beyond the schema, simply reiterating the concept of deleting by key.

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 ('Delete') and identifies the resource ('previously stored memory') and the mechanism ('by key'). It clearly distinguishes itself from sibling tools like 'remember' and 'recall' by being the deletion 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?

It explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with 'remember and recall,' providing clear situational triggers and complementary workflow 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 readOnly, idempotent, openWorld, and non-destructive behavior. The description adds valuable process context: it fetches a page, extracts key elements, and outputs a single text blob. It doesn't mention potential failure modes, but the annotations lower the burden, and the behavior is well-articulated.

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-load the purpose and process, with a compact 'Useful for' list. It is concise and structured logically, though the phrase 'production-ready' and 'standard llms.txt markdown format' are slightly redundant. Still very efficient.

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

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

Given no output schema, the description explains the output format ('standard llms.txt markdown format', 'single text blob') and gives use cases. It lacks error-handling details or limitations, but the tool is simple (2 params, strong annotations) and the description covers the essentials well.

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%—both `url` and `max_links` have descriptions in the schema. The tool description adds little beyond the schema; it mentions 'key links' but does not reference the `max_links` parameter or its default behavior. Baseline of 3 is appropriate since the schema carries the parameter documentation.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL.' It explains the process (fetches page, extracts title/description/key links, emits standard markdown) and is distinct from all sibling tools, none of which mention llms.txt.

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 clear context for use via the 'Useful for:' list, covering client work, personal projects, and competitive auditing. However, it does not explicitly exclude alternatives or mention when not to use this tool, so it stops short of a 5.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds value by disclosing the exact informational payload that will be returned (fields, geometry type, record count, capabilities), which helps the agent set expectations. No contradiction with annotations.

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

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

A single, dense sentence that front-loads the verb and resource, lists outputs, and includes the URL qualifier. No wasted words.

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

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

For a simple one-parameter read-only tool, the description covers the what, the input, and the expected return contents. Given no output schema, this provides sufficient context for an agent to understand the tool's results and differentiate it from query operations.

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 sole parameter 'url' is fully documented in the schema with a type and example. The tool description only references 'by url' without adding new details, so it does not enhance the schema's already complete parameter coverage.

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

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

The description uses a specific verb ('Get'), identifies the resource ('ArcGIS Feature/Map Service layer's schema'), and enumerates the exact output contents (fields, geometry type, record count, capabilities), clearly distinguishing it from data-query siblings like query_layer.

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

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

The description implies its use case (schema retrieval by URL) but does not explicitly state when to prefer it over alternatives or exclude scenarios. The presence of sibling query_layer suggests a distinction, but the description does not articulate this contrast.

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, and non-destructive behavior. The description adds value beyond annotations by specifying the return fields (id, type, params, etc.) and the default active-only scope. No contradictions with annotations.

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

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

Two sentences, no fluff. The first sentence states the action and return fields, the second gives usage guidance. Information is front-loaded and every word 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 list tool with one optional parameter and rich annotations, the description covers purpose, usage, and return fields. The lack of an output schema is compensated by listing return fields. Complexities like pagination or errors are not relevant for this straightforward read operation.

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

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

Schema coverage is 100% for the single parameter include_inactive, which has a clear description. The tool description does not elaborate further on the parameter, so the schema carries the semantic load, warranting the baseline score of 3.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and lists the exact return fields. It also differentiates from sibling tools like subscribe and unsubscribe by framing the use case for reviewing monitoring and finding ids to cancel.

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

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

The description gives explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' While it doesn't name alternatives directly, the context implies that subscribe/unsubscribe are the complementary tools, making the when-to-use clear.

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

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

The description discloses that filing without an account returns a `claim_token` that can be passed back later to check resolution status, a rate limit of 5 per identifier per day, and that it's free with no quota impact. These behaviors are not covered by the annotations, which only set all hints to false.

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 containing multiple distinct pieces of guidance (purpose, exclusions, token workflow, rate limits). While every sentence adds value, it could benefit from structural segmentation (e.g., bullets), but overall it is informative without significant 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?

Given no output schema and minimal annotations, the description covers the tool's full interaction model: what to report, how to identify relevant tools, token-based follow-up, rate limits, and context structuring. It lacks only a detailed return format, which is unnecessary for a feedback tool.

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

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

The input schema already documents all parameters with 100% coverage, including enum meanings and the claim_token workflow. The description adds context about token return without an account and mentions structuring context around Pipeworx tools/packs, but most parameter meaning is already in the schema.

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

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

The description explicitly states the tool's function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names the specific resource (Pipeworx team) and differentiates it from other MCP servers' tools, making it clear this feedback applies only to this connection's tools.

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

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

It enumerates exact use cases (bug, feature, data_gap, praise) and provides explicit exclusions: if the tool is from a different MCP server, 'file it with that server instead.' It also advises describing issues in terms of Pipeworx tools/packs rather than pasting user prompts, giving clear when-to-use guidance.

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

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

The description adds significant context beyond annotations: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This discloses data provenance, privacy, output shape, and caching behavior, which the annotations do not cover.

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

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

The description is three sentences, front-loaded with the core function, followed by a numbered use-case list and then behavioral details. Every sentence adds distinct value, with 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 simple read-only tool with one optional parameter and no output schema, the description fully covers purpose, return values (top tools, packs, call volume), use cases, and behavioral characteristics. The '(pack, tool, count)' hint compensates for the absent output schema.

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

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

Schema description coverage is 100% for the only parameter, and the schema already explains the default and the trade-off between window lengths. The description repeats the window options 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 clearly states what the tool does with a specific verb and resource: 'Returns the top tools, top packs, and total call volume over a recent window.' It distinguishes from siblings by focusing on aggregate usage trends of other AI agents, not individual discovery or search.

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

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

The description explicitly lists three concrete use cases, including 'confirming a popular tool is the canonical choice before asking your own question.' This provides clear when-to-use guidance and implies alternatives (e.g., asking directly) without naming sibling tools.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses rich behavioral traits such as the fill check against live CLOB depth, the rule that realizable_edge_pp <= 0 means the overround exists only at last-trade, the Jaccard similarity threshold for semantic pairing, and the partition placeholder filter. These are not in the annotations and add significant context for the agent.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the core purpose. Every segment adds necessary detail for a complex tool; however, the length itself borders on verbose, so a perfect score is not warranted.

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

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

For a tool with no output schema, the description fully explains response shapes (opportunities[], partition_check fields), mode-specific behaviors, edge cases (placeholder slugs, low similarity, thin legs), and when not to trade. Combined with the detailed annotations, an agent has everything needed 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?

Although the schema already covers both parameters (event and topic), the description adds substantial meaning: example slugs, the distinction between single-event and cross-event behavior, how each mode processes markets, and what the semantic anchor does. This goes well beyond the schema's basic 'event slug' and 'topic' 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 and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool from siblings by describing distinct modes (trending_scan, event, topic) and explicitly recommends polymarket_fill_risk for custom sizing, showing awareness of the tool landscape.

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

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

The description provides explicit when-to-use guidance: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also states for which scenarios to use event vs topic, and explicitly directs custom sizing to polymarket_fill_risk, giving an alternative.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description goes far beyond this, disclosing the math behind edge calculations (lognormal barriers, GDELT ratios, overround corrections), Kelly caps, slippage handling, the 24h-move warning, and even the 1-hour KV-level cache. No contradictions.

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

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

The description is extremely dense and runs as a single block with uppercase labels instead of bullets or paragraphs. Every sentence is informative, but readability suffers. There is also an apparent discrepancy: it says 'FIVE MODEL FAMILIES' but lists only four (crypto_price, news_momentum, partition_overround, concentrated_longshot). While not a functional issue, it shows a lack of polish.

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 the response. It details top-level fields (by_segment, fed_candidates, _diagnostics), explains why segments might be empty (stale top-N, failed gates, knob filters), and describes caching behavior. It is exceptionally complete for a tool with 9 parameters and zero required fields.

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

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

Schema coverage is 100%, but the description adds crucial inter-parameter context: min_kelly only filters single-leg opportunities, min_partition_leg_kelly applies per-leg inside top_legs, and slippage_pp is subtracted before ranking. It clarifies why min_kelly doesn't filter partition arbs and explains how categories map to the three segments. 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 the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes from siblings by detailing three specific segments (model-driven, structural arbitrage, concentrated longshot) and the response structure, making it unique among the sibling tools.

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

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

The description frames usage as 'what should I bet on today' and provides context for when to adjust tradeable-edge knobs like min_liquidity and max_spread_pp. It does not explicitly exclude sibling tools, but the detailed segment breakdown implies appropriate use cases. The note about Fed bets and when they're unreliable adds good decision 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/non-destructive, but the description adds substantial behavioral context: 60-day snapshot TTL, snapshot start time, cache-miss writing behavior, daily-close basis for decay, and interpretation of negative edge_pp_net. This goes well 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 but well-structured, using labeled sections (Args, RESPONSE, LIMITS) and front-loading the core purpose. Every sentence conveys necessary information; there is no filler, and the structure aids scannability.

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 thoroughly documents the response structure (tracked[], expired[], snapshot_dates[]) and their semantic meanings, including the 'competition clock' interpretation of median lifespan. It also explains historical limitations, making it complete for the tool's complexity.

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

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

The input schema covers both parameters fully with descriptions (days lookback, window family). The description repeats defaults and adds that window is a 'snapshot family', but does not significantly extend parameter semantics. With 100% schema coverage, a 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 tool's purpose as 'edge persistence and decay telemetry' built from daily polymarket_edges snapshots, and articulates the specific question it answers ('how long has this edge existed and is it shrinking?'). This distinguishes it from sibling tools that likely focus on 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 implies when to use the tool by focusing on historical persistence and decay, contrasting fresh vs old edges. It provides clear context but does not explicitly name alternative tools or give 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?

Despite having readOnlyHint, idempotentHint, and destructiveHint annotations, the description goes well beyond them. It reveals that the tool walks the order-book ladder, that theoretical overround on thin books is not capturable, and that partial basket fills convert an arb into an unhedged directional position. This is deep behavioral context that materially affects how an agent should interpret results.

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

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

The description is dense but carefully structured with ALL-CAPS mode labels (SINGLE-MARKET, BASKET, USE THIS) and front-loads the core purpose in the first sentence. Every sentence delivers necessary information for a two-mode tool, and the length is justified by 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?

For a tool with no output schema, the description enumerates every output field for both modes (top_of_book, vwap_fill_price, capture_ratio, thin_legs, forced_directional_risk, etc.), explains the size_usd interpretation per mode, and states defaults and clamps. It also provides the risk context that matters for an agent deciding when to call this tool. Nothing critical appears omitted.

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

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

Schema coverage is 100%, but the description adds critical semantics missing from the schema: side meaning differs per mode (sell_yes captures overround in basket mode), size_usd is interpreted as max spend on buys vs target proceeds on sells vs settlement notional in basket mode, and exactly one of market/event is required. This enriches the schema descriptions significantly.

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+object: 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' clearly distinguishing it from the sibling arb/edge tools. It also explicitly names the two modes (single-market and basket), leaving no ambiguity 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 an explicit trigger: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' and explains the risk that necessitates it. However, it does not state when not to use the tool or name alternative tools for different scenarios, 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?

The description goes far beyond the annotations by explaining safety fields and edge cases: compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs. matched_pairs:0 with skipped_cross_type:0 and >5 legs), temporal_alignment and its implication ('aligned:false means spreads are mathematically meaningless'), and the skipped_cross_type/subtype counters. This provides deep behavioral transparency that annotations alone do not offer. No contradiction with readOnlyHint/idempotentHint.

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

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

The description is long but well-structured with explicit headers (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core concept in the first sentence. Some repetition exists in the final warning, but overall each section contributes value and the structure aids scanning.

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

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

Given the lack of an output schema, the description compensates by explaining the response format ('leg-by-leg prices... matched spread[].top_spreads_pp') and covering key edge cases (compatibility_warning, temporal_alignment, skipped_cross_type). It is comprehensive for the tool's complexity, though it could be slightly more explicit about parameter combination behaviors (e.g., what happens if only one override is provided).

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

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

Schema coverage is 100%, so all parameters have descriptions. The tool description adds meaningful semantics beyond the schema by explaining the two modes and the override relationship: 'Overrides the topic-mapped Kalshi side.' It also embeds parameter usage in the context of custom pairings, which enhances understanding.

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

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

The description opens with a specific verb+resource statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly distinguishes the tool from sibling tools like polymarket_arbitrage by focusing on cross-venue comparisons and explicitly naming the two venues. It also details two distinct modes, further clarifying its 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 clearly states when to use the tool: for comparing spreads between Kalshi and Polymarket on the same question. It explains the two usage modes (topic shortcuts vs. explicit ticker/slug) and provides a strong caution: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests... pre-mapped ≠ tradeable.' However, it does not name alternative tools for other scenarios, so it falls short of explicit when-not/alternatives guidance.

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

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

Annotations already declare readOnlyHint=true, but the description adds that it returns attribute rows and geometry, and describes SQL-like filtering behavior. The sampling tip and explicit mention of output format go beyond the annotations, providing useful behavioral context. No contradiction with annotations.

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

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

Two sentences: first states purpose and key parameters, second gives a usage tip. No fluff, well front-loaded with the verb and resource. Every word 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?

With no output schema, the description's mention of returning rows and geometry helps fill that gap. It also references the predecessor tool (search_datasets) and provides a sample query pattern. Overall, it is fairly complete for a query tool, though it could include pagination behavior notes beyond offset.

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 value by explaining SQL-like semantics ('where', 'out_fields', 'order_by') and giving a practical sampling pattern. It enhances rather than repeats schema info, justifying a score above baseline.

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

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

The description clearly states the tool queries an ArcGIS Feature/Map Service layer by URL, using a specific verb ('Query') and resource. It distinguishes from sibling tools like layer_info (metadata) and search_datasets (dataset discovery) by focusing on data retrieval.

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

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

It indicates the URL comes from search_datasets, implying a workflow of first finding a dataset then querying it. The sampling tip ('Use where="1=1" + out_fields="*"') provides concrete usage context. However, it does not explicitly exclude alternatives or state when not to use, leaving some ambiguity.

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 this as a read-only, idempotent, non-destructive operation, so the description doesn't need to restate that. It adds valuable context beyond the annotations by explaining that the tool is scoped to an identifier (anonymous IP, BYO key hash, or account ID) and that omitting the key lists all keys. This gives the agent a clearer picture of the tool's behavior and privacy boundaries.

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 but information-dense. Every sentence serves a purpose: the first defines the primary action and list behavior, the second gives practical examples, the third explains scoping, and the fourth points to complementary tools. There is no redundancy or fluff.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all necessary context: what it does, when to use it, how it's scoped, and how it fits into the larger tool ecosystem. The agent has enough information to decide when to invoke this tool and what to expect from it.

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

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

The schema already documents the key parameter with 'Memory key to retrieve (omit to list all keys)', providing 100% coverage. The description reinforces this and adds semantic examples of what kinds of keys are useful (target ticker, address, research notes), which helps the agent understand the intended usage beyond the raw schema.

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

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

The description states exactly what the tool does: retrieves a previously saved value or lists all saved keys when the key argument is omitted. It uses a specific verb ('Retrieve') and resource (saved memories), and clearly distinguishes itself from the sibling tools by referencing remember and forget, which are the companion save/delete 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?

The description explicitly tells when to use the tool: to look up context the agent stored earlier, such as the user's target ticker, an address, or prior research notes, without re-deriving it. It also names the complementary tools (remember to save, forget to delete), providing a clear usage context and alternatives.

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

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

The description reveals a side effect: setting mark_read:true flags events as read, which modifies state. This directly contradicts the readOnlyHint=true annotation, making it an annotation contradiction. The description otherwise adds useful context about return fields and external access, but the contradiction forces a score of 1.

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 well-structured: it starts with the primary action, then details return fields, filtering, and mark_read behavior, and ends with polling and an alternative endpoint. No redundant information.

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

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

For a tool with five optional parameters and no output schema, the description covers main functionality, return fields, and usage nuances like polling and an external URL. However, the annotation contradiction and lack of explicit mention of unread_only slightly reduce completeness.

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

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

The schema covers all parameters with descriptions, but the description adds practical meaning by giving an example for type ('sec_8k') and explaining the behavioral effect of mark_read on future calls. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, using a specific verb and resource. It distinguishes itself from siblings like list_subscriptions by focusing on alert events and their payloads.

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 on how to use the tool, including filtering by type and since, and setting mark_read. It also mentions polling and an alternative URL for scripts, but does not explicitly compare with sibling tools or state when not to use it.

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

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

Beyond the read-only/idempotent annotations, the description discloses specific behaviors: fans out to multiple sources in one parallel call, fallback logic (GDELT→GNews), and a known limitation (USPTO soft-fails due to PatentsView sunset). It also describes return structure and citation URIs, adding significant value beyond annotations.

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

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

The description is a single focused paragraph with a clear lead-in, examples, mechanism, and alternative. Every sentence contributes, and it remains readable despite covering multiple data sources and the `since` parameter formats.

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?

Though no output schema exists, the description compensates by specifying the return shape: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' It also covers edge cases like rate-limiting and API sunset, making it fully contextual 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?

Schema covers all parameters (100%), but description adds semantic value by explaining accepted date formats and giving usage examples ('Use "30d" or "1m" for typical monitoring'). It reinforces parameter meaning without redundancy.

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

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

The description clearly states the tool's purpose with vivid examples ('What's new with X' / 'latest on Y') and a precise definition: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It distinguishes from sibling entity_profile by contrasting the static profile vs. change feed 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?

Explicit when-to-use guidance is given through example queries and by stating it fans out to multiple sources. It also tells when NOT to use it: 'Use entity_profile instead when you want the static profile... regardless of window.' This directly guides tool selection among siblings.

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

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

The description goes beyond the annotations by explaining key-value scoping, persistence differences for authenticated vs anonymous sessions, and the 24-hour retention limit. This is valuable behavioral context not captured in the idempotentHint.

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

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

The description is front-loaded with the core purpose, followed by usage guidance and behavioral details. Every sentence adds necessary information without 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 memory-write tool, the description covers purpose, usage, persistence, scoping, and related tools. No output schema exists, so the absence of return-value details is acceptable.

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 documents both parameters fully with examples, so the baseline is 3. The description reinforces the key-value concept but doesn't add significant syntactic detail 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 opens with a specific action ('Save data') and clearly identifies the resource and purpose. Examples (resolved ticker, target address) and the contrast with recall/forget distinguish it from sibling memory tools.

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

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

The description explicitly states 'Use when...' and gives concrete scenarios. It also names recall and forget as complementary tools, providing clear 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?

The description provides rich behavioral context beyond what annotations convey. It details cascading lookups through multiple endpoints, graceful degradation (if GLEIF or OpenFIGI is unavailable, EDGAR identifiers still return), and output labeling (identifiers have source labels, unresolved ones are stated explicitly). This aligns with and complements the readOnlyHint, idempotentHint, and destructiveHint=false annotations, with no contradictions.

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

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

The description is front-loaded with the core purpose and usage guideline, then delves into technical details about sources and degradation. While every sentence adds value, the length (several paragraphs) borders on verbose. It could be slightly condensed without losing clarity, but it remains well-structured and informative.

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

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

Given the tool's complexity (multiple entity types, multiple data sources, graceful degradation), the description covers input requirements, behavioral expectations, and edge cases well. However, without an output schema, it only hints at the return structure (labels, unresolved list) but does not provide an example or explicit format, leaving a minor gap in completeness.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds significant value by expanding on the 'value' parameter with concrete examples (ticker, CIK, ISIN, name for company; brand or generic name for drug) and clarifying the scope of the 'type' parameter. This helps an agent understand acceptable input formats beyond the schema's concise descriptions.

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

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

The description clearly defines the tool's purpose: resolving a user-provided name to canonical/official identifiers needed by other tools. It provides specific example queries (e.g., 'What's the ticker for…') and distinguishes between two supported entity types (company and drug), making the function unmistakable. The purpose is unique among sibling tools like compare_entities or entity_profile.

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

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

The description explicitly states 'Use FIRST whenever you have a name but need an ID,' giving clear priority guidance. It also explains that the tool replaces 2-3 manual lookups. While it does not list specific alternatives for when not to use it, the context and sibling list imply that other tools (e.g., entity_profile) are for working with existing IDs. This is strong but could be improved by explicitly mentioning alternatives.

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

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

The description discloses that it probes each entity with ai_visibility_check, ranks by score, and returns ranked metrics (score, confidence, signal density). This adds behavioral context beyond the annotations (readOnly, openWorld, idempotent) without contradicting them. It does not mention potential rate limits or cost implications of multi-probing, but the core behavior is transparent.

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

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

The description is three sentences with no fluff. It front-loads the purpose, explains the method (probes with ai_visibility_check, ranks), and gives a concrete use case and output summary. 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?

With no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density). It also covers the mechanism and use case. It doesn't discuss error handling or limitations, but given strong schema coverage and annotations, this is sufficient for a multi-entity comparison tool.

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

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

Schema coverage is 100%, and the entities parameter description already includes the 'first entry as subject' semantics that the description paraphrases. The description adds no extra parameter meaning beyond what the schema provides, 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's function: compare AI visibility across multiple entities side-by-side, probe each with ai_visibility_check, and rank results. This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by emphasizing multi-entity AI visibility and ranking.

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

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

It gives a clear context for when to use: competitive AI-marketing audits, and an illustrative example question. It implies a multi-entity scope but doesn't explicitly name alternatives or exclusion scenarios, such as 'for single entity use ai_visibility_check'. This fits the 'clear context, no exclusions' level.

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

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

Even with annotations readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description goes further by disclosing graceful degradation, potential 5-30s delay on first measurement, and the presence of a 'sources_failed' field in output. This adds real behavioral context beyond annotations and does not contradict them.

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

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

The description is information-dense yet every sentence earns its place: purpose, use cases, output summary fields, ecosystem limitation, and failure behavior are all covered without excessive wording. The structure front-loads the core purpose and uses a closing sentence for caveats, making it easy to scan for key details.

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

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

Given the tool's complexity (two external APIs, multiple output components) and the absence of an output schema, the description is remarkably complete. It lists the summary block fields, mentions per-advisory detail, links, alternative versions, and explicitly addresses failure/timeout behavior. It also clarifies the ecosystem boundary, leaving no major contextual gaps.

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

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

Schema description coverage is 100%, and the description does not add meaning beyond what the schema already provides. It mentions that the version defaults to latest, but that is also in the schema. The description repeats no explicit parameter details beyond those in the schema, so a 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 opens with a specific verb+resource: "Composite 'should I add this npm package to my project' check in ONE call" and clearly distinguishes the tool from siblings by naming the two data sources (deps.dev and bundlephobia). It uniquely addresses npm package evaluation among the sibling list, so there is no ambiguity about its 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?

Explicit usage triggers are given: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'." It also provides an exclusion for non-npm ecosystems, stating "PyPI / Maven / Cargo / Go fall under deps.dev:version directly," which tells the agent when NOT to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing it as a safe read-only operation. The description adds value beyond annotations by specifying the exact return fields (name, summary, record_count, owner/org, url) and the fact it returns a Feature Service URL, which informs the agent of the output structure. No contradiction with annotations.

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

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

The description is two sentences: the first front-loads the purpose and scope, the second details return fields and downstream usage. Every word contributes value, with no filler or redundancy. Ideal length 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?

Given three optional parameters and no output schema, the description adequately covers what the tool does, what it returns (explicitly listing fields), and how the returned URL is used with sibling tools. It does not explain pagination or sorting behavior, but those are not critical for a search tool where the schema covers limit. The description is sufficiently complete for an agent to use it correctly.

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

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

Schema coverage is 100% for all three parameters, each with meaningful descriptions (query keywords, limit range, optional org_id). The description adds minimal extra parameter semantics; it simply restates 'by keyword' which aligns with the query parameter. Baseline 3 is appropriate because the schema already handles parameter documentation.

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

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

The description clearly states a specific verb ('Search') and resource ('Lorain County GIS open geospatial datasets') with concrete examples of searchable content (parcels, addresses, zoning). It distinguishes itself from sibling tools by explicitly noting it returns Feature Service URLs for query_layer/layer_info, which is an effective differentiator.

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

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

The description implies clear usage context: use this to discover datasets by keyword, then pass the returned URL to query_layer or layer_info for further operations. It does not explicitly state when not to use this tool or name alternative search methods, but the downstream guidance is a strong usage signal. Slightly below a 5 because exclusions are not mentioned.

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

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

Even though annotations already declare readOnly, idempotent, and not destructive, the description adds valuable behavioral details: the embedding model (BGE-base-en), cosine similarity over 500-char windows, the 200K char cap with truncation flagging, and the return format (passages with offsets and similarity scores). These details go well beyond the annotations and help the agent predict output and edge cases.

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

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

The description is a bit long (5 sentences) but every sentence contributes: purpose, usage, pairing, and technical implementation. It front-loads the core purpose and then adds supporting detail. No filler words; the structure is logical and efficient.

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

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

Despite lacking an output schema, the description explains the return format ('top-N passages with character offsets and similarity scores'), the underlying algorithm, and the character cap. It also covers the integration with ask_pipeworx_grounded, making it a complete picture for the 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?

Schema description coverage is 100%, so the schema already documents each parameter. The description reinforces the semantics with examples ('SEC 10-K body', 'natural-language query') and mentions 'top-N' passages, but it does not add significant new meaning beyond the schema's parameter descriptions. It meets the baseline but doesn't elevate it.

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

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

The description clearly states the tool's function as 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K, article). It distinguishes itself from siblings by framing it as a tool for searching within an already-fetched record, and even names ask_pipeworx_grounded as a complementary tool, making its unique purpose explicit.

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 when the record is too big to cram into the prompt' and explains how it pairs with ask_pipeworx_grounded. This tells the agent exactly when to use this tool and how it fits into a larger workflow, effectively differentiating it from alternatives.

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

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

Annotations already declare readOnly=false and idempotentHint=true, and the description adds useful behavioral context: it requires OAuth, returns the new subscription ID, notes that SMS has a 10/day cap and requires phone verification. However, it omits the webhook delivery channel entirely (including its HMAC signing and auto-disable behavior), which is a significant gap when the schema supports it.

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

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

The description is front-loaded with the core purpose and then organized by requirements, types, and delivery channels. It is fairly efficient, but somewhat redundant with the schema (e.g., repeating SMS verification and 10-day cap), and what it omits (webhook, two types) might require the agent to consult the schema. Overall, it is concise enough for its 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?

The tool is moderately complex with nested params and no output schema, so the description carries a heavy burden. It covers OAuth requirements, return ID, and some delivery details, but omits webhook as a delivery channel and two of the five subscription types (patent_grant, clinical_trial). It also does not mention that the response includes a webhook signing secret when webhook is specified. These are clear gaps that could cause an agent to under-utilize or misunderstand the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples and interpretations (e.g., 'items:["5.02"] = officer change') and clarifying the 'polymarket_edge' topic parameter. However, it only covers three of the five allowed types, leaving patent_grant and clinical_trial undocumented in the description, though the schema covers them.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It uses the verb 'create' with a specific resource, and the rich detail about supported types and delivery channels distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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 on prerequisites ('Requires a Pipeworx OAuth account') and how to consume the always-on feed ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'). However, it does not explicitly state when to use this tool versus alternatives (e.g., list_subscriptions for viewing), nor does it explain when not to use it beyond the OAuth requirement.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds valuable behavioral context: that it returns category-bucketed examples with exact tool + argument shape, drawn from a live catalog, and that it works with no arguments or with an optional topic. This goes 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 long but every sentence serves a purpose: it lists query phrasing, explains the return value, gives concrete categories, clarifies the optional parameter, and explicitly states when to use it. The structure is front-loaded with the entry-point intent, then details, and ends with usage guidance. No wasted words.

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

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

Given the tool's simplicity (1 optional param, no output schema, read-only), the description is complete. It covers what the tool returns, the categories, the parameter behavior, and use cases. The output is fully characterized (category-bucketed examples with tool + argument shape), so no output schema is needed. This is a complete description for the tool's complexity.

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

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

Schema coverage is 100% and the `topic` parameter is documented with enum-like values. The description reinforces the parameter by listing examples and explaining the effect of omitting it (full spread). This adds value by contextualizing what 'focus' means and by providing example values not fully captured in the concise schema description.

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

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

The description uses specific verbs ('onboarding entry point') and explicitly states resource ('Pipeworx') and scope ('category-bucketed example questions'). It distinguishes from siblings by naming the meta-tools (ask_pipeworx, entity_profile, compare_entities) as the things it teaches, making the purpose clear and unique.

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 says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This is explicit guidance on when to use, and it implicitly excludes other tools by redirecting to them. It also offers a clear alternative: call with `topic` to focus, or omit for the full spread.

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 discloses ownership enforcement (only your own subscriptions) and the deactivation behavior (row not deleted, historical events remain in recent_alerts). This aligns with the destructiveHint=false annotation and adds significant behavioral context.

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

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

Two sentences, front-loaded with the primary action, and no redundant information. Every sentence earns its place by covering purpose, constraints, and side effects.

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 low-complexity tool with one parameter and annotations, the description is complete: it states the purpose, ownership rule, deactivation behavior, and where historical events can be found (recent_alerts). No output schema is necessary for a void operation.

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

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

The schema provides 100% coverage for the single parameter, describing it as 'Subscription id (uuid) returned by subscribe.' The description adds no additional parameter-level detail, 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 begins with a specific verb and resource: 'Cancel a subscription by id.' It clearly differentiates from sibling tools like subscribe and list_subscriptions, and additionally clarifies that the operation deactivates rather than deletes.

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

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

The description implies when to use the tool (when you need to cancel a subscription) and provides important context about ownership and soft-deletion. It does not explicitly name alternatives or exclusions, but the context is unambiguous given the sibling tool names.

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

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

The description adds substantial behavioral context beyond annotations: it explains the meaning of each verdict, especially the critical distinction that 'could_not_verify' means the check failed and must not be interpreted as evidence. It also discloses routing logic and the exact pipeline behavior, which annotations like readOnlyHint and openWorldHint do not cover.

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 fairly long but well-structured, front-loading the core purpose and using a clear format with returns, caveats, and a summary of replaced calls. Some phrases are slightly redundant (e.g., 'routed to the right live source, answered with verbatim evidence, then judged'), but overall the length is justified by 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?

This tool has no output schema, so the description carries full responsibility for explaining return values and behaviors. It covers the verdict set, citation mechanism, reasoning, and the important error semantics, making the description self-sufficient for an agent to understand the tool's full contract and edge cases.

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

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

While the schema fully documents both parameters, the description enriches the semantics of tolerance_pct with concrete guidance (e.g., set 1–2 for hallucination detection) and the default behavior. It also provides examples for the claim parameter, giving real-world clarity beyond the schema's type-only description.

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

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

The description clearly identifies the tool's function: verifying natural-language factual claims against authoritative sources. It uses specific trigger phrases and lists concrete example intents, and it distinguishes itself from sibling tools by explaining that it replaces multiple sequential calls with a single end-to-end verification flow.

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 whenever the agent needs to check whether something a user said is factually correct') and clarifies the two distinct pathways for financial vs. other claims. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of the exhaustive 'when-not/alternatives' bar.

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