Arcgis Raleigh

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

Annotations already declare read-only and idempotent, so the description adds value by disclosing external LLM calls, the cost implication of using Anthropic (BYO key), and the default free model. It also outlines the return structure, providing behavioral context 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 three sentences, front-loaded with purpose, then key details (default model, cost), and ends with use cases. Every sentence earns its place, with no filler or repetition.

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 explains the return structure (per-model {score, confidence, signals, raw_response} + combined view). It covers purpose, models, cost, and use cases. It could add more on failure handling or rate limits, but the current content is fairly complete for the tool's complexity.

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

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

Schema coverage is 100%, with each parameter described. The description adds value by explaining the free vs. paid model choice and the cost implication of `_apiKey`, but this is largely redundant with the schema descriptions, 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 verb 'Probe' and the resource 'LLMs', with a specific output of visibility scores (0-100) per model. It distinguishes itself from sibling tools by focusing on multi-model probing and scoring, and mentions the default model and optional Anthropic probing.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to add the Anthropic key. It does not explicitly name alternatives or state when not to use, but the context is clear enough.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral context: it routes questions across tools, fills arguments automatically, and returns stable pipeworx:// citation URIs. It also hints at a citation-trust caveat by redirecting to ask_pipeworx_grounded where citations are the priority.

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 key guidance ('PREFER OVER WEB SEARCH') and is information-dense without being wasteful. The many examples are justified for such an open-ended entry-point tool, though the final breaking-news sentence is slightly cluttered.

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

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

For a tool with one required natural-language parameter, no output schema, and strong safety annotations, the description covers inputs, usage context, alternatives, and return shape well. It clearly states that output is a structured answer with citation URIs, so an agent has enough context to invoke it correctly.

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

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

Schema coverage is 100%; every parameter is documented as an alias for the single natural-language question. The description contributes useful example queries, but it does not add new parameter constraints, formats, or semantics beyond what the schema already communicates, so the baseline score applies.

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

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

The description states the exact purpose: it answers factual questions about current or historical data by routing to a large set of verified tools and sources, then returns a structured answer with pipeworx:// citation URIs. It clearly distinguishes itself from ask_pipeworx_grounded and deep_research, so an agent can tell this tool apart from its siblings.

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

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

The description gives explicit trigger phrases such as "what is", "look up", "find", "get the latest", and "how much". It also states when not to use it: multi-hop questions that should fan across sources should use deep_research, and cases where citations are unreliable should prefer ask_pipeworx_grounded.

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

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

Adds important behavior beyond annotations: this is an experimental router, live improvements may be enabled at any time, and responses/results are compared against a stable router. It also confirms that today, with no active candidate. However, it could better suggest how active experiments could affect the response quality or 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 front-loaded with its primary purpose and current status, which is good. The precise retirement date of the last candidate and the 'falls back to nothing' clarification add useful context but are slightly verbose, making the description a touch less concise.

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

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

Given the single required parameter, existing annotations, and a no-output-schema tool, this description covers everything needed: what the tool is, how it relates to the stable ask_pipeworx, when to use it, and what the response promises are. No critical contextual gap remains.

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

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

Schema coverage is 100% and the schema already documents question and its aliases. The description only repeats 'same arguments, same response shape,' so it adds no new parameter-specific meaning.

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

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

The description clearly identifies the tool as a beta variant of ask_pipeworx, an identical universal question router, and distinguishes it from the stable ask_pipeworx by calling out its experimental nature. The reference to the same 5,596 tools, arguments, and response shape pins down its exact 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?

Explicitly states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It names the stable counterpart and clarifies current, immediate behavior. A responsible agent can decide between this and the stable router without inference.

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

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

The description adds important behavior beyond annotations: it explains the grounded extraction contract, refusal_reason options, and the extra LLM call cost. It also makes clear that the tool will decline to answer when evidence cannot be directly extracted from the tool result. No contradiction with the readOnlyHint/openWorldHint annotations.

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

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

The description is front-loaded with the high-level behavior, then adds return/refusal structure and usage guidance. Every sentence contributes something distinct: purpose, routing, output behavior, use cases, and cost tradeoff. Despite length, there is no filler or redundant content.

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

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

The description covers the core behavior, expected output fields, refusal cases, the tradeoff compared to the sibling tool, and the recommended context. Given there is no output schema, this description fully compensates by specifying the return shape and refusal reasons explicitly. The agent has enough information to invoke and interpret the result correctly.

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

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

Schema description coverage is 100% and the schema already fully documents that all parameters are aliases for a natural-language question. The description itself adds no additional parameter syntax/format details, but it does reinforce that the question is natural language in context of high-stakes routing. This is adequate but entirely schema-driven.

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 is a hallucination-resistant grounded answer mode, with a specific verb/action (picks a tool, fetches data, extracts answer) and distinguishes itself from sibling ask_pipeworx. It also clarifies the underlying routing and evidence constraints, making the purpose immediately identifiable.

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 tells when to use this tool ('high-risk reads', 'whenever an answer will be quoted, cited, or acted on') and when to prefer ask_pipeworx ('casual lookups'). It also gives clear examples of high-stakes domains, leaving no ambiguity about the boundary between grounded mode and the cheaper alternative.

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

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

The description discloses extensive behavioral traits beyond annotations: the resolver contract with market_match_confidence, the low-confidence short-circuit, closed-market blocking, wide-spread illiquidity note, cancellation-rule parsing, and news fallback handling. These are critical operational details not implied by readOnlyHint or idempotentHint. The description aligns with the annotations (readOnly, idempotent, non-destructive) and adds significant context on 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 long but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY). It is front-loaded with purpose and usage, then dives into critical edge cases. While some examples are extensive, each carries actionable guidance for correct invocation. It is not terse, but the density of vital operational detail justifies the 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?

There is no output schema, so the description carries the full burden of explaining return values. It thoroughly covers result.market, result.analysis, result.evidence, parent_event extraction, market_match_confidence, status codes, and resolution-rule risk. Given the tool's complexity and missing output schema, this description is unusually complete.

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

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

Schema coverage is 100%—all three parameters (market, depth, include_raw) have descriptions. The description itself reiterates the market input format (slug/URL/question text) but does not materially add parameter semantics beyond the schema. The depth and include_raw behaviors are explained only in the schema, not the description. Thus a baseline of 3 is appropriate.

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

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

The description opens with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' This uses a specific verb (research), a clear resource (Polymarket bet), and distinguishes itself from siblings like polymarket_edges or validate_claim by focusing on the data-fan-out approach for bet research. It also provides concrete use-case phrases ('should I bet on X') that map directly to the tool's intent.

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

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

The description explicitly states 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and gives multiple fan-out examples per category. This clearly implies when to use the tool. However, it does not explicitly state when not to use it or name alternative sibling tools, which would push it to 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 discloses specific data sources (SEC EDGAR/XBRL, FAERS, FDA), metrics pulled (revenue, net income, cash, long-term debt; adverse-event counts, approval counts, trial counts), sorting behavior, citation URI format, and performance benefit (replaces 8–15 lookups). This goes well beyond the annotations' read-only/idempotent hints.

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

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

The description is appropriately sized and front-loaded with trigger phrases, then moves to behavioral specifics. Every sentence adds value—no filler, and the structure is logical: triggers → preferred usage → type-specific behavior → output format → efficiency.

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

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

Given the absence of an output schema, the description fully covers what the tool returns (paired data + citation URIs), how results are sorted, per-type data pulled, and limitations (2–5 entities). It also addresses the context of sibling tools by distinguishing parallel comparison from sequential lookups. Minor details like error cases are absent but not critical for a read-only tool with rich annotations.

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 already covers both parameters at 100%, the description adds meaningful semantic detail: it explains what each 'type' value means operationally (company pulls 10-K financials, drug pulls FAERS/FDA/trial counts) and gives concrete examples for 'values' (['AAPL','MSFT'], ['ozempic','mounjaro']). 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 a specific verb and resource: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It also distinguishes from siblings like entity_profile by emphasizing parallel multi-entity comparison rather than single-entity lookup.

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

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

Explicit guidance is provided: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also explains when each type is appropriate (company vs drug) and provides concrete trigger phrases for when to invoke this tool.

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

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

The description goes well beyond annotations: it discloses account/auth requirements, parallel decomposition across ~5,600 tools, the findings packet structure, gaps[] behavior, contradictions[], hop stages, citation fetchability, excerpting, and expected latency. This matches the readOnly and idempotent annotations with no contradiction.

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

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

The description is long but densely packed with operational value. Key gating info, alternatives, and cost constraints upfront, followed by clear mechanics and output contract. Every sentence contributes to correct selection and invocation.

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 the full burden of explaining return behavior — and it does, including evidence, confidence, source, fetched_at, pipeworx citations, gaps[], contradictions[], hop, deletable excerpts, and timing. Prerequisites and alternatives are also covered, making the description effectively complete.

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

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

The input schema already documents both parameters thoroughly, including depth semantics, so the description is not the sole source of parameter meaning. It adds some useful detail beyond the schema: the paid-plan requirement for thorough, the single-hop vs. gap-recovery behavior, and the recommendation to keep multi-part questions in one call.

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?

States an explicit verb and resource: 'Grounded multi-source research across Pipeworx's 1465 structured data sources ... in ONE call' and explicitly says 'this is NOT open-web search.' It clearly differentiates itself from siblings like ask_pipeworx and from broad question types.

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

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

Provides explicit when-to-use and when-not-to-use guidance: use for broad/multi-part structured-data questions; use ask_pipeworx for single lookups, breaking/colloquial topics, and for users not signed in. This gives clear routing logic with named alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds return-behavior details (top-N tools with names, descriptions, schemas, curated examples, ready-to-call, no second lookup) and strategic 'call first' guidance, giving context beyond the safety annotations.

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

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

Three sentences, front-loaded with a clear purpose, followed by domain lists and return behavior. No fluff; the domain enumeration is relevant for a tool that spans many data types.

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

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

For a discovery tool with no output schema, the description explains what it returns, when to use it, and what domains it covers. Combined with rich schema and annotations, it leaves little ambiguity.

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

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

Schema covers 100% of parameters with descriptions and aliases; the description simply restates the query concept ('describing the data or task'). Baseline 3 is appropriate since the description adds marginal semantic value 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 'Find tools by describing the data or task,' clearly identifying a search/discovery meta-tool. It lists supported domains and explicitly states it returns tool names, descriptions, and schemas, distinguishing it from sibling tools like search_datasets that search data rather than 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?

Provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also hints at when-not ('not just one answer'), though it doesn't name alternative tools directly.

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

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

Annotations already declare read-only and idempotent, so the bar is lower. Description adds meaningful context: it documents a soft-fail for the patents API (sunset May 2025), a GDELT→GNews fallback, and that it fans out in parallel. It does not mention error handling or rate limits, but these are partially covered by openWorldHint.

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: examples, main definition, what it returns, and constraints. Every clause adds necessary information, and the semicolon-separated return list makes it scannable. It is not as tight as a two-sentence description, but the density is justified given no output schema.

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 for return values. It lists each field (cik, filings, fundamentals, patents, news, LEI) and even gives URI format hints. It covers input formats, limitations, and alternatives. This is as complete as a text description can reasonably be for a complex tool.

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

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

Input schema has 100% description coverage for both parameters. The description reinforces with examples ('AAPL', '0000320193') and explicitly states names are not supported, which adds value beyond the schema (though schema already says 'Names not supported'). Since schema covers most, baseline is 3, and the extra examples and clarification push it to 4.

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

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

The description opens with concrete trigger phrases and defines the tool as a 'full cross-source profile of a US public company in ONE parallel call.' It explicitly differentiates from siblings by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and mentions using resolve_entity for names, making the purpose and scope unambiguous.

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

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

Provides explicit when-to-use ('when the user asks for a holistic view') and a when-not-to-use ('names not supported — use resolve_entity first'). Also mentions the alternative approach (chaining single-pack lookups) to avoid, giving clear usage direction.

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 destructiveHint=true and idempotentHint=true, so the agent knows this is a safe-to-repeat but destructive operation. The description adds use-case context but no new behavioral traits (e.g., irreversibility, missing key behavior). It does not contradict annotations.

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

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

Two sentences, front-loaded with the primary purpose, followed by usage guidance and sibling references. No unnecessary detail or repetition.

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 tool with no output schema, the description, combined with rich annotations (destructive, idempotent), provides sufficient context for an agent to select and invoke it correctly. It covers purpose, usage, and related tools.

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

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

The input schema fully documents the 'key' parameter with a clear description ('Memory key to delete'), giving 100% coverage. The description repeats 'by key' and adds the context of 'previously stored' but does not enrich the parameter semantics beyond the schema 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 action ('Delete') and resource ('a previously stored memory by key'), distinguishing it from siblings 'remember' and 'recall' which store and retrieve memories respectively. It is a specific verb+resource pairing.

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

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

Explicitly states when to use the tool with three concrete conditions (context stale, task done, clear sensitive data). It also mentions pairing with related tools 'remember' and 'recall', providing clear guidance on alternatives.

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

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description discloses the tool's process: it 'fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This gives agents a clear model of what happens when invoked, including the output being a single text blob ready for placement.

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 well-structured sentences: the first states purpose, the second outlines the process, and the third lists use cases. Every sentence earns its place, with no redundant or filler content.

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

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

Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description is complete. It explains the output format ('single text blob ready to drop at site-root/llms.txt'), the process, and the use cases, covering all essential context an agent needs to invoke it correctly.

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

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

The input schema provides 100% coverage for both parameters (url and max_links) with clear descriptions. The description adds no extra parameter syntax or constraints beyond what the schema already states, fitting the baseline of 3 for high schema coverage.

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

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

The description clearly states the tool's function: generating a production-ready llms.txt file for any URL. It uses a specific verb ('Generate'), names the resource ('llms.txt file'), and distinguishes itself from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on file generation for AI crawler indexing.

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 use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), which serves as clear usage guidance. However, it does not explicitly state when not to use the tool or mention alternative tools, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying the output components (fields, geometry type, record count, capabilities), which are not in the annotations. It does not contradict the annotations and provides useful behavioral context about what the tool retrieves, though it does not cover rate limits/auth or network 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 a single sentence that front-loads the verb ('Get') and resource, then lists all key return elements without extraneous words. Every clause earns its place, making it highly efficient and easy to parse.

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

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

For a simple one-parameter tool with no output schema, the description fully explains what the tool returns (fields, geometry type, record count, capabilities). Annotations cover safety and idempotency. This provides enough context for an agent to select and invoke the tool without missing critical information.

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

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

The schema has 100% description coverage for the single 'url' parameter, including an example. The description merely says 'by url' without adding new semantic details beyond what the schema already provides. Since the schema does the heavy lifting, the baseline 3 is appropriate; the description does not enhance or clarify the parameter beyond the property 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 starts with 'Get an ArcGIS Feature/Map Service layer's schema by url' – a specific verb and resource. It enumerates the exact payload: fields (name + type), geometry type, total record count, and capabilities. This clearly distinguishes it from sibling tools like query_layer (data querying) and search_within (searching), making the purpose unambiguous.

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

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

The description clearly implies when to use this tool: when you need schema/metadata of an ArcGIS layer, not actual feature data. It does not explicitly mention alternatives or exclusion cases (e.g., 'use query_layer for data'), but the context is strongly inferred from the explicit return fields and the sibling list. There is no misleading guidance, so it earns a 4.

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 hints. The description adds behavioral context by specifying it returns the caller's active subscriptions (scope) and enumerates the return fields, which goes beyond what annotations provide. It doesn't mention pagination or limits, but for this simple list tool it's adequate.

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: first states purpose and return fields, second gives usage guidance. Every word earns its place with no redundancy, and it is front-loaded with the core purpose.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete: it explains what is returned, the default active-only behavior, and when to use it. The annotations and schema cover safety and parameters, so no critical information is missing.

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

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

Schema coverage is 100% for the single optional parameter include_inactive, which is fully described in the schema. The description indirectly refers to active subscriptions (implying default behavior) but doesn't add significant new meaning beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and lists the returned fields (id, type, params, etc.), making the tool's purpose unambiguous. It distinguishes itself from sibling mutation tools like subscribe/unsubscribe by being a read operation.

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 scenarios: 'review what you're monitoring before adding more' and 'to find an id to cancel.' While it doesn't name alternative tools, the context makes it clear when this tool is appropriate, so it falls just 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 are all false, so the description carries the full burden. It discloses substantial behavior beyond structured fields: anonymous filing returns a claim_token, that token can later be passed back to read resolution status, the team reads digests daily, there is a rate limit of 5 per identifier per day, and the tool is free. This gives the agent a clear model of what happens when the tool is invoked.

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

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

The description is dense but every sentence earns its place: purpose, usage triggers, exclusion rule, content guidance, claim_token behavior, rate limit, and cost. It is efficiently structured with semicolons and front-loaded with the primary purpose, making it easy to scan for key decision points.

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

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

Despite having no output schema and uninformative annotations, the description is complete for this tool's complexity. It explains the input context, the output/claim_token behavior, how to follow up, the routing constraint, and practical constraints like rate limiting. There are no material gaps for an agent to select and invoke this tool correctly.

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

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

The schema already covers all parameters at 100% with detailed descriptions, so the baseline is 3. The description adds meaningful semantic guidance beyond the schema: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' and 'pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'. This enriches parameter usage beyond the schema definitions.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly identifies the tool as a feedback channel and immediately distinguishes it from the research, visibility, and data-centric sibling tools like ask_pipeworx and discover_tools.

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

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

The description gives explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a crucial exclusion: reports about tools from other MCP servers should be filed elsewhere, with a test for identifying Pipeworx tools. This is exemplary usage guidance.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals important behavioral traits: the data is aggregated from a CF analytics-engine, contains no PII, is limited to (pack, tool, count), and is cached for 5 minutes to 1 hour depending on window. This adds meaningful context about freshness and privacy that annotations do not 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 concise and front-loaded with the purpose, then a compact returns statement, then a numbered list of use cases, then two short notes on aggregation/privacy and caching. Every sentence earns its place without unnecessary jargon or repetition.

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 optional parameter and no output schema, the description is complete: it states the return contents, the aggregation source, privacy guarantees, caching behavior, and concrete use cases. No significant gap remains for an agent to invoke it correctly.

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

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

The only parameter, window, is already fully documented in the schema with enum values and guidance about short vs. long windows, so schema_coverage is 100%. The description restates the option values and the schema's semantic guidance but adds little beyond that; the caching note implies window-dependence but does not elaborate on parameter choice.

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

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

The description opens with a clear plain-language statement of what the tool does (shows what other AI agents are calling on Pipeworx) and then states concrete outputs: top tools, top packs, and total call volume over a window. This is specific and distinguishes it from sibling tools like search_datasets or ask_pipeworx by framing it as a self-aggregating usage signal.

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

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

The description explicitly enumerates three use cases with 'Useful for,' giving an agent clear context for when to call this tool, including discovering hot data sources and confirming canonical tool choices. It does not mention when not to use it or name alternative tools, preventing a 5.

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

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

Annotations already declare readOnly/openWorld/idempotent, so the bar is lower, but the description adds substantial behavioral context: the partition placeholder filter, the ≥0.30 Jaccard similarity threshold, the >3pp deviation trigger, and the fill_check caveat that a signal may not be realizable at the book. These go well beyond the annotations.

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

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

The description is long but well-structured with SCREAMING section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the primary usage. Every section adds unique value, though the density makes it slightly less scannable than an ideal concise description.

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

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

Given no output schema, the description thoroughly explains return values (opportunities[], partition_check, fill_check) and covers all three modes, including edge cases and limitations. It is self-sufficient 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 coverage is 100% with both event and topic described, but the description adds concrete examples ('fed-decision-may-2026'), differentiates the two modes, and explains the cross-event behavior and similarity anchoring. This meaningfully extends the schema definitions.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from sibling tools like polymarket_fill_risk by focusing on discovery and signal generation rather than fill execution.

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: 'Call with NO args for a trending_scan... pass event for... or topic for...' and 'For custom sizing use polymarket_fill_risk.' It also tells users not to trade when realizable_edge_pp ≤ 0, giving clear decision boundaries.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds substantial behavioral context: it discloses the 1h KV cache keyed on all knobs, explains the five model families and their response segmentation, describes the 24h-move warning, and details the _diagnostics structure so callers understand why a segment might be empty. 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 information-dense and front-loads the purpose, but it's a long wall of text that dives into model-formula specifics (lognormal barrier, GDELT ratios, per-sport α values) that could be summarized or sectioned. While every sentence adds technical detail, it lacks structural organization (no paragraphs/headers) and is longer than necessary for an agent to decide to call the 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?

Despite lacking an output schema, the description thoroughly covers the response top-level (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, market fields), and filter/drop behavior, making it sufficient for an agent to understand what the tool returns and why. It also explains the caching behavior and knobs, so the tool is well-specified for complex usage.

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 earns a 4 by explaining how tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) interact with the model outputs, and by providing parameter guidance (e.g., slippage_pp bump/drop advice and how min_kelly doesn't apply to partition arbs). This adds meaning beyond the schema's per-parameter descriptions.

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

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

The description opens with a specific verb+resource pair: 'Scan top Polymarket markets and return opportunities' and immediately states the unique value prop ('what should I bet on today'), clearly distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker. It also names the three model segments, giving a complete picture of the tool's function.

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 frames the intended use case ('Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets') and explains the role of tradeable-edge knobs and filters in refining results. However, it doesn't explicitly name alternative tools for different use cases or state when not to use it, so it gets a 4 rather than 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?

Beyond the readOnlyHint and non-destructive annotations, the description exposes key behavioral traits: it is based on daily snapshots, has a 60-day TTL, uses cache-miss-driven snapshotting (explaining gaps), and computes decay from daily closes rather than intraday data. This is exactly the kind of context that affects interpretation and goes beyond what annotations provide.

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

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

The description is long but every sentence earns its place. It is front-loaded with the core question, then clearly sections args, response format, and limits. The response field explanation is structured with semicolons and bullet-like 'tracked[]', 'expired[]', and 'snapshot_dates[]'. No filler; all details are operationally relevant.

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

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

The tool has no output schema, so the description must explain return values—it does comprehensively, including the meaning of trend, decay_pp_per_day, expired opportunities, and snapshot_dates. It also covers limitations (TTL, snapshot writing conditions, daily close basis). For a telemetry tool with interpretive nuance, this is as complete as one could expect.

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

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

The schema already covers both parameters with clear descriptions (lookback days, window family enum). The description adds meaning by framing 'window' as a 'snapshot family' and clarifying defaults (days default 14, window default '1wk'). It also explains the semantics of days in context (lookback for snapshots), which has slightly more nuance than the schema's 'clamp 2-30'. Since schema coverage is 100%, baseline is 3, and the description adds interpretive value.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and uses a specific verb ('answers'). It implicitly distinguishes itself from sibling polymarket_edges by focusing on temporal tracking rather than current edge values, though it does not explicitly name an alternative.

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 strong contextual guidance: it contrasts a fresh wide edge with a 3-week-old one, implying use for evaluating edge persistence. It also explains the meaning of the response fields (e.g., 'the median lifespan is your competition clock'). However, it does not explicitly state when NOT to use it or name sibling alternatives, though the purpose itself makes the alternative (polymarket_edges) obvious.

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 destructiveHint=false, but the description adds substantial behavioral context: it details the two modes, what metrics are returned (slippage, max_fillable, etc.), and the danger of partial basket fills turning arb into directional exposure. No contradiction with annotations.

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

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

The description is long but densely packed, with clear structure using uppercase mode labels and semicolons. Every sentence adds operational value—no fluff. It is appropriately detailed for a tool with two distinct modes and complex return semantics.

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

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

With no output schema, the description fully compensates by enumerating return values (top_of_book, vwap_fill_price, slippage_pp, shares_filled, etc.), covering edge cases (thin_legs, forced_directional_risk), and providing warnings about partial fills. It is operationally 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?

Although schema coverage is 100%, the description enriches parameter meaning significantly. It explains that `size_usd` is 'max spend on buys, target proceeds on sells' in single-market mode, and 'settlement notional S (shares per leg)' in basket mode. It also clarifies `side` defaults per mode, which the schema only briefly states.

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

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

The description opens with a clear, specific purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and is clearly different from sibling tools like polymarket_arbitrage or polymarket_edges, which focus on finding edges rather than assessing fill risk.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why, warning about thin books and unhedged directional risk, effectively steering the agent away 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 mark idempotent/read-only, but the description adds substantial behavioral detail: compatibility_warning triggers, temporal alignment constraints, skipped_cross counters, and the explicit statement that most pre-mapped topics return warnings. This goes far beyond the structured 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 long but logically structured with clear sections (purpose, modes, response, safety fields). It front-loads the core purpose and uses uppercase labels for scannability. Some redundancy exists (e.g., repeating the warning about rare spreads), but each sentence delivers meaningful 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?

Without an output schema, the description thoroughly explains the response structure, including leg prices, spread, safety fields, and edge cases like temporal alignment and skipped comparisons. It also covers both modes and parameter interactions, making the tool self-contained 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 coverage is 100% with descriptive parameter explanations, but the description adds interaction semantics: how explicit tickers override topic, the full list of macro shortcuts, and how the two modes relate to response generation. This enriches understanding beyond the schema's individual property 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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, with specific detail on how the two venues may price outcomes 2-25pp apart. It distinguishes itself by focusing on cross-venue comparison and explicitly mentioning when bet shapes are equivalent, setting it apart from sibling tools like polymarket_arbitrage.

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

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

The description explains two modes (topic shortcuts vs explicit event IDs) and when each is appropriate, including parameter override behavior. It also warns that pre-mapped topics often yield compatibility warnings and are 'pre-mapped ≠ tradeable', providing useful when-not guidance. It does not explicitly compare to alternative tools, but the context is clear enough.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds that the tool returns attribute rows and geometry, and hints at SQL-like querying behavior. It doesn't detail pagination or rate limits, but that's not critical given the annotation coverage.

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

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

The description is concise (four short sentences), front-loaded with the core purpose, then lists parameters, return type, and a usage example. It wastes no words and is easy to scan.

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 rich schema and strong annotations, the description provides sufficient context: what it does, how to use it, and what it returns. It lacks error handling details, but for a read-only query tool with a well-defined schema, the description is adequately complete.

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

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

Schema coverage is 100%, so the schema fully documents all parameters. The description restates the key parameters (where, out_fields, order_by, limit, offset) and adds the sampling tip, but adds 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 queries an ArcGIS Feature/Map Service layer by URL, which is a specific verb+resource combination. It also mentions it's meant for layers found via search_datasets, distinguishing it from sibling tools like search_datasets and layer_info.

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

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

The description indicates a workflow by saying 'from search_datasets' and provides a concrete sampling tip (where='1=1' + out_fields='*'). It doesn't explicitly name alternatives or exclusion cases, but the usage context is clear enough for an agent to know when to use this tool.

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

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

The annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true; the description is fully consistent. It adds beyond the annotations by disclosing the scoping behavior ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the optional listing behavior when key is omitted.

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

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

Three sentences, front-loaded with the primary action, then usage context and scoping/pairing info. No redundant or filler content.

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

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

For a simple 1-param tool with no output schema, the description covers the action, the return behavior (value or list of keys), scoping, and relationship to sibling tools. This is complete for the tool's complexity.

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

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

Schema coverage is 100% with the 'key' parameter described. The description adds semantic value by giving example key values (ticker, address, research notes) and explicitly stating that omitting the key lists all saved keys, reinforcing the schema's 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 the specific verb 'Retrieve' and names the resource as 'value previously saved via remember', plus the alternative 'list all saved keys'. It clearly distinguishes from siblings by explicitly referencing remember and forget. The examples of use cases (target ticker, address, research notes) reinforce 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?

It states when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It explicitly names alternatives with 'Pair with remember to save, forget to delete,' providing clear guidance on tool selection.

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

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

Annotations already declare read-only/idempotent, but the description adds critical behavioral context: mark_read mutates read state (affects future calls), each alert's payload structure, and the existence of a direct HTTP endpoint. This goes beyond annotations without contradicting them.

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

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

Four sentences, each earning its place: purpose, return payload, filtering/read-state behavior, and alternative access. Front-loaded and free of 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 5 optional parameters, good annotations, and no output schema, the description covers return payload, filtering, read tracking, and alternative access. It is complete for the tool's complexity without needing to explain schema-covered details.

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 meaning by explaining mark_read's effect on subsequent calls ('so the next call only shows newer ones') and gives an example of type ('sec_8k'). It doesn't redundantly restate all schema details, but adds useful semantics.

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

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

Uses a specific verb-phrase ('Pull fired events') and identifies the resource ('your subscription feed'). It clearly distinguishes from siblings like list_subscriptions (which lists subscriptions, not events) and recent_changes (likely about changes to something else). The mention of the persisted feed and evaluator-written alerts adds unique context.

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 usage context: polling is fine, filtering by type/since, and mark_read semantics for incremental reads. It explicitly mentions an alternative access path (GET endpoint) for scripts/dashboards, though it doesn't directly contrast with 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 annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses significant behavioral traits: it fans out to SEC EDGAR, GDELT→GNews with a rate-limit/5xx fallback, and USPTO which soft-fails due to a sunset API. It also states the return structure (changes[], total_changes, pipeworx:// URIs), giving a clear picture of side effects and limitations.

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

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

The description is dense but every sentence adds value: purpose, sources, fallbacks, return format, and alternative tool. It is front-loaded with user-facing example queries, making it immediately clear what the tool does. Despite its length, it contains no redundant or filler content.

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

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

Given the tool's complexity (multiple sources, fallback logic, structured output) and the absence of an output schema, the description adequately covers all necessary information: return structure, source behavior, caveats, and when to use an alternative. It also aligns with annotations, making it a fully contextualized description.

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

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

Schema coverage is 100%, so the baseline is 3 per the rubric. The description does not add significant new parameter meaning beyond the schema; it reinforces the same examples for `since` and `value`. The only extra is a usage tip ("30d" or "1m" for typical monitoring), which is minor and more about usage than semantics.

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

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

The description clearly states the tool's purpose: a change feed for a company in the last N days/weeks/months, with example queries like "What's new with X" and "latest on Y". It also distinguishes from sibling entity_profile by specifying it returns a time-windowed change feed rather than a static 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?

It explicitly tells when to use this tool vs entity_profile: "Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window." It also provides recommended usage for the `since` parameter ("Use '30d' or '1m' for typical monitoring") and explains fallback behavior, setting expectations for when sources degrade.

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 indicate this is a write operation (readOnlyHint false) and idempotent (idempotentHint true). The description adds meaningful behavioral context: storage is 'scoped by your identifier,' and persistence differs for authenticated users (persistent) vs anonymous sessions (24 hours). This goes beyond what annotations provide.

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

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

Four sentences, front-loaded with the core purpose, followed by usage guidance and persistence details. No wasted words; each sentence earns its place.

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

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

For a simple two-parameter store tool with full schema coverage and annotations, the description fully covers purpose, usage, and behavioral context. No output schema is needed since return behavior is uncomplicated.

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

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

Schema coverage is 100% with both key and value already described, including examples. The description reinforces the key-value relationship and scoping, but adds minimal new parameter-level detail beyond the schema's own 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 'Save data the agent will need to reuse later' with a specific verb and resource (key-value store). It distinguishes from sibling tools recall and forget by explicitly naming them for retrieval and deletion.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with examples. Also names alternatives: 'Pair with recall to retrieve later, forget to delete,' making the usage context and tool selection clear.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds significant behavioral context: graceful degradation (if GLEIF or OpenFIGI unavailable, EDGAR identifiers still return), internal cascading through multiple endpoints, and explicit mention of unresolved identifiers. 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 verbose but well-structured. It front-loads with usage guidance and examples, then logically breaks down supported types and fallback behavior. Every sentence provides value, though some parts (like the ISIN-to-LEI detail) could be slightly condensed without losing clarity.

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

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

Given the complexity of the tool (two entity types, multiple identifier sources, no output schema), the description is remarkably complete. It covers input variations, output expectations (including unresolved identifiers), fallback behavior (degradation), and internal cascading. No output schema exists, but the description explains return value structure sufficiently.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds rich semantics well beyond the schema. It explains what 'company' and 'drug' types entail (e.g., company includes CIK, ticker, LEI, FIGI; drug includes RxCUI, ingredient, brand). It details input formats (ticker, CIK, ISIN, name) and output behavior (unresolved identifiers listed separately). This fully compensates for the schema's brevity.

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

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

The description clearly states it resolves user-spoken names to canonical/official identifiers. It provides concrete examples like 'What's the ticker for...' and explicitly says 'Use FIRST whenever you have a name but need an ID.' This distinguishes it from sibling tools such as entity_profile and compare_entities.

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

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

The description gives explicit guidance to use this tool first when you have a name but need an ID. It includes example queries and notes that it replaces multiple manual lookups. However, it does not explicitly state when NOT to use it or name specific alternative tools for already-resolved identifiers.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, and signal density per entity. This goes beyond the annotations to describe the mechanism and output, without contradiction.

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

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

Three sentences, each earning its place: the first states the core purpose, the second explains the mechanism and output, the third gives a concrete use case. Front-loaded, no redundancy, and appropriately sized for the tool's complexity.

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

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

Given the moderate complexity, the description covers the workflow (probing, ranking) and output shape (ranked list with fields), the schema documents all parameters, and annotations handle safety. The only minor gap is the absence of performance/cost discussion (e.g., time for multiple probes), but this is not essential for a read-only comparison tool.

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

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

The input schema covers 100% of parameters with detailed descriptions, so the baseline is 3. The description reinforces that the first entity is treated as the subject ('your brand + N competitors') but does not add new syntax, format, or constraints beyond what the schema provides. It is consistent but not additive.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the resource (AI visibility), the action (compare), and the output (ranked list), distinguishing it from the single-entity sibling tool ai_visibility_check by emphasizing the multi-entity, side-by-side nature 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?

The description provides a concrete use case ('competitive AI-marketing audits') and an example query ('does Claude know about us as well as our competitors?'), making clear when to use the tool. It implicitly positions itself as the multi-entity alternative to ai_visibility_check, but it does not explicitly name or exclude other sibling tools like compare_entities.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral traits beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and the composite fan-out nature. This helps set latency expectations and explains the `sources_failed` field.

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 but front-loaded with the core purpose, followed by usage, return fields, ecosystem scope, and failure behavior. Every sentence earns its place with no wasted words, and it is appropriately sized for the tool's complexity.

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

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

For a composite tool with no output schema, the description thoroughly covers what the tool returns (summary block fields, per-advisory detail, links, alternative versions), its ecosystem limitation, and its failure modes. This is complete enough for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100%, with both `package` and `version` fully described in the schema. The description does not add parameter-specific semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool is a composite 'should I add this npm package' check, naming specific data sources (deps.dev, bundlephobia) and the kinds of data returned (license, advisories, bundle size, etc.). It also distinguishes this tool from siblings by specifying NPM-only scope and pointing to deps.dev:version for other ecosystems.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small"...' It also gives a clear exclusion for non-NPM ecosystems, directing to deps.dev:version directly. This tells the agent exactly when to use this tool and when to look elsewhere.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the description only needs to add context beyond that. It does so by listing the exact return fields (name, summary, record_count, owner/org, Feature Service URL) and the downstream integration with other tools. This provides useful behavioral detail without contradicting annotations.

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

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

The description is two sentences, front-loaded with the action and resource, and every sentence adds value. It includes examples of search terms and explains the output's downstream use without unnecessary verbosity.

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

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

Given no output schema, the description adequately specifies the return fields and directs the agent to the next steps (query_layer/layer_info). It does not detail response structure (e.g., array vs object), but the zero-parameter requirement and schema coverage reduce the need for additional context. The description is complete enough for an agent to invoke the tool and interpret results.

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

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

The input schema already fully describes all three parameters (query, limit, org_id) with 100% coverage. The description adds no additional parameter-level detail, so the baseline of 3 applies. The description does not clarify parameter interactions beyond what the schema already states.

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 ('Search') and identifies the exact resource ('City of Raleigh GIS open geospatial datasets'), including examples of content (parcels, zoning, parks, transport & city services). It clearly distinguishes itself from sibling tools by stating the output is a Feature Service URL to pass to query_layer/layer_info, establishing its role as the discovery/search step.

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 a workflow: use this tool to search datasets, then pass the returned URL to query_layer or layer_info. This gives clear context for when to use it relative to those siblings, though it does not explicitly mention alternative search tools or when not to use it. Still, the guidance is unambiguous for the primary use case.

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, so the safety profile is covered. The description adds valuable behavioral detail beyond annotations: returns passages with offsets and similarity scores, uses BGE-base-en embeddings + cosine over 500-char overlapping windows, and 200K cap with truncation flag. No contradiction.

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

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

Three dense, purpose-driven sentences. The first sentence states the action and return format, the second gives usage guidance and pairs with a sibling tool, the third details technical behavior. No fluff; each 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?

No output schema exists, so the description must convey return values; it does—'top-N passages with character offsets and similarity scores.' It also covers input limits, embedding method, truncation flag, and usage scenario. For a tool with this complexity, the description is complete enough for an agent to 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?

Schema description coverage is 100% for all three parameters, so the baseline is 3. The description adds extra meaning by explaining text is 'already pulled,' giving concrete examples of document types, and specifying truncation behavior (200K cap 'flagged'), which goes beyond the schema's simple 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 states a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from siblings by emphasizing input is text already pulled (e.g., SEC 10-K body, article) and by naming ask_pipeworx_grounded as a complementary tool, avoiding confusion with broader search tools.

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

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

Explicitly says when to use: 'Use when the record is too big to cram into the prompt.' It also names an alternative/complement: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear context and an explicit 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 provide readOnlyHint: false, idempotentHint: true, destructiveHint: false, and openWorldHint: true. The description adds substantial behavioral context: auth requirements, phone verification for SMS, a 10/day SMS cap, webhook HMAC signing, and auto-disabling after 10 consecutive failing runs. It also clarifies that the feed is always on and how to pull from it. 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 dense and front-loaded with the primary purpose. It is organized by subscription type and delivery channel, which aids readability. However, it is a long single paragraph with many nested clauses; using bullet points would improve scannability. Every sentence adds value, but the overall structure could be more concise.

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

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

Given the tool's complexity (3 parameters, nested objects, multiple subscription types, delivery channels, no output schema), the description is remarkably complete. It covers return value, authentication, delivery channel behavior, constraints, and failure handling. It explains what happens for each type and includes examples. The absence of an output schema is compensated by stating the return type 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%, so the baseline is 3. The description adds meaningful value beyond the schema by providing concrete examples for each type (e.g., sec_8k items:["5.02"], polymarket_edge topic:"fed") and clarifying constraints like phone verification and the 10/day cap. The delivery object's webhook details (signing secret, signature verification) are also elaborated 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 verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly indicates the tool's function (creating subscriptions) and distinguishes it from siblings like list_subscriptions and unsubscribe. The return value is stated: 'Returns the new subscription id.'

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

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

The description provides clear context on when to use the tool: it requires a Pipeworx OAuth account, and notes that anonymous and BYO users cannot persist subscriptions. It also gives examples for each subscription type and mentions an alternative for pulling alerts ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'). However, it does not explicitly say when not to use it versus sibling tools like list_subscriptions or unsubscribe beyond implying a lifecycle.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the description does not need to repeat these. It adds valuable context beyond annotations: that the tool pulls from a 'live catalog of thousands of tools', returns category-bucketed examples, and includes the exact tool call shape. This enriches the agent's understanding of what the tool actually does without over-explaining.

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 relatively long, but every sentence carries useful information for an onboarding tool. The initial list of example phrasings ('what can I ask?', 'getting started', etc.) might seem redundant, but it serves the tool's purpose of recognizing user intents. The structure is acceptable and front-loaded with the core function, though it could be tightened slightly without losing value.

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

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

Despite having no output schema, the description explains what the tool returns: 'category-bucketed example questions (company financials, drugs & clinical trials, economics, ...) each with the exact tool + argument shape'. It also covers the parameter behavior and the intended use case. For a simple tool with one optional parameter, this is complete and leaves no major questions 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?

The schema already describes the `topic` parameter with allowed values (100% coverage). The description adds extra semantics by providing examples ('finance', 'pharma', 'betting') and explaining the effect of omission: 'Call with no arguments for the full spread.' This goes beyond the schema's bare list and helps the agent make a more informed choice about when to supply `topic`.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions, each with the exact tool and argument shape. This distinguishes it from siblings like discover_tools and ask_pipeworx by focusing on what questions to ask rather than what tools exist. The specificity of 'returns category-bucketed example questions' and 'exact tool + argument shape' makes the purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to use it with or without the topic parameter. It does not explicitly mention when not to use it or alternative tools, but the context is clear enough for an agent to select it appropriately.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds meaningful behavioral context: it explicitly states that ownership is enforced (auth requirement) and that the operation is a deactivation, not a deletion, preserving historical events in recent_alerts. This enriches the agent's understanding of side effects.

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

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

The description is three sentences long, front-loaded with the core action, and every sentence contributes essential information: the action, the access constraint, and the non-destructive side effect. No fluff or repetition.

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

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

For a tool with one parameter and no output schema, the description is fully sufficient. It covers the action, the ownership rule, the deactivation behavior, and the link to recent_alerts for historical data. The annotations handle the rest (idempotency, non-destructive flag), leaving no significant gaps.

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

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

The input schema already documents the id parameter as a uuid returned by subscribe (100% coverage), so the baseline is 3. The description adds value by clarifying that the id must refer to a subscription the caller owns, which is a meaningful semantic constraint on the parameter.

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: 'Cancel a subscription by id.' It clearly distinguishes this tool from its siblings (subscribe, list_subscriptions) by action and effect, and the title 'Unsubscribe from Alerts' reinforces the purpose.

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

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

The description provides clear usage context by stating ownership enforcement ('only cancel your own subscriptions') and the soft-delete behavior ('row is deactivated, not deleted'). However, it does not explicitly contrast this tool with alternatives or state when not to use it, so it falls short of a 5.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses critical behavioral semantics: the meaning of 'could_not_verify' (check did not happen, carries verification_error, must not be shown as evidence) and 'unsupported' (no source exists). It also details return values (verdict, actual value with citation, reasoning) and the internal routing logic. This adds substantial context 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?

Despite being long, the description is front-loaded with trigger phrases and structured logically: purpose, routing behavior, return values, error semantics, and added value. Every sentence contributes distinctive information, and the length is justified by the tool's complexity. No filler or redundancy is present.

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

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

Given no output schema, the description fully compensates by explaining the verdict values, the citation format, the distinction between could_not_verify and unsupported, and the underlying pipeline. It also covers edge cases (verification_error) and practical rationale (replacing sequential calls). The tool's complexity is high, and the description leaves no significant gap for an agent to invoke it correctly.

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

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

Schema coverage is 100%, and the description adds meaningful semantic value on top: it explains that tolerance_pct overrides wording-implied tolerance and gives a use-case example (hallucination detection with 1–2%). The claim parameter is illustrated with realistic examples. While the schema already describes parameters, the description enriches their practical usage context.

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 with specific verbs and trigger phrases ('fact check', 'verify the claim that…', 'confirm or refute') and explicitly defines it as 'natural-language claim verification against authoritative sources.' It also distinguishes its scope from other tools by outlining the structured SEC EDGAR fast path for financial claims versus the grounded pipeline for all other factual claims, making it unique among siblings.

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

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

The description provides explicit usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies routing behavior (financial vs. non-financial claims) and notes that it replaces multiple sequential calls. However, it does not explicitly state when not to use the tool or offer alternative sibling tools, so it falls short of full '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.