Arcgis Roanoke

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

The annotations already declare readOnly, openWorld, and idempotent hints. The description adds valuable context beyond these: default model is free (Workers AI Llama-3.3-70b), Anthropic calls require a BYO key and cost the user directly, and the return structure includes per-model fields. No contradiction with annotations.

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

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

Three dense sentences: the whole description is under 350 characters, front-loaded with the primary action, then model details, return shape, and use cases. Every sentence carries distinct information; 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?

Despite no output schema, the description specifies the return fields ({score, confidence, signals, raw_response} + combined view). Combined with 100% parameter schema coverage and well-disclosed annotations (read-only, idempotent), the only marginal gap is explaining what 'signals' means, but this is a minor nuance. The description fully equips an agent to invoke the tool.

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

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

Schema descriptions provide 100% coverage, but the description enriches key meanings: it explains the default/free model, the meaning of `_apiKey` (BYO, you pay Anthropic), and the semantics of omitted `models` (default to workers-ai). This adds value beyond the raw schema, though slightly redundant with 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: 'Probe one or more LLMs for what they know...' and defines the output as a visibility score (0-100) per model. It distinguishes itself from siblings by focusing on LLM knowledge scoring, clearly relevant to AI-marketing audits and brand checks.

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

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

Usage context is clear: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to pass `_apiKey` (to probe Anthropic) and the default model. However, it does not explicitly state when not to use it or mention alternative tools for related tasks.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds behavioral context: routing mechanics, argument filling, citation URI return, and performance ('one fast call', 'works on every tier'), which goes beyond the annotation surface.

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 directive and uses concrete examples to convey scope. While lengthy, each part (alternatives, examples, routing details) contributes value and no filler 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?

No output schema exists, so the description compensates by explaining the return format (structured answer with citation URIs). It also covers use cases, alternatives, and starting phrases, making it complete for the tool's complexity.

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

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

Schema covers 100% of parameters, all aliases for 'question', with descriptions. The description adds example queries and scope guidance but no additional parameter-level syntax, so baseline 3 applies.

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

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

The description clearly states the tool routes questions to 5,529 tools and returns structured answers with citations, identifying it as a factual QA/discovery tool. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point.

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 instructs to prefer this over web search and to start here for most questions. Provides specific alternatives: ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part queries, plus examples of trigger phrases.

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 valuable context: no candidate is currently active, so it matches ask_pipeworx exactly, and it is a full working router, not a stub. It also discloses the comparison-to-stable behavior, which is useful beyond annotations.

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

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

The description is dense but compact, covering purpose, current state, usage, and assurances in three sentences. The specific date and tool count add useful context without excess fluff. It could be slightly shorter, but every sentence carries 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?

Given the tool's complexity as a beta router with dynamic behavior, the description adequately covers the current operational state, equivalence to the stable version, and usage context. It references the sibling for full details, which is acceptable since ask_pipeworx exists in the same family.

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 all six parameters described as aliases for 'question'. The description adds no parameter-specific meaning beyond saying 'same arguments as ask_pipeworx', which is baseline. Since the schema already documents aliases, the description's contribution is minimal.

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 version of ask_pipeworx, an identical universal router with candidate routing improvements. It distinguishes from the stable sibling by emphasizing the experimental edge and current equivalence to ask_pipeworx. However, it does not explicitly state the end-user function (e.g., answering questions via routing), relying on the sibling's known behavior.

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

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

The description gives explicit guidance: use it 'exactly like ask_pipeworx when you want the newest routing,' and notes that results are compared against the stable router to decide merges. This clearly positions it against the sibling and implies stable ask_pipeworx is the alternative when not wanting experimental routing.

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/idempotent annotations, the description discloses the exact return format, possible refusal reasons, the extra LLM call cost, and that it uses only the tool result content. This goes well beyond what annotations provide.

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

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

The description is concisely structured: opening purpose, return structure, refusal cases, usage guidance, and tradeoff. Every sentence earns its place and it is front-loaded with the most important information.

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

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

For a single-question tool, the description fully covers purpose, behavior, output structure, refusal modes, usage context, and cost tradeoff. The lack of an output schema is compensated by a detailed description of the return shape.

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 the question parameter and aliases. The description adds no parameter-specific details beyond noting that the tool 'fills arguments' and that the question is natural language, so it meets baseline but doesn't exceed it.

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

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

The description clearly states what the tool does: provides hallucination-resistant answers by extracting from tool results with evidence. It explicitly distinguishes from ask_pipeworx by highlighting the grounded extraction and additional cost.

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

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

It explicitly states when to use this tool (high-stakes reads, answers to be quoted/cited/acted on) and when to prefer ask_pipeworx (casual lookups), along with the cost difference.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses many non-obvious behaviors: resolver match-confidence contract, parent_event extraction, news fallback logic, low-confidence short-circuit behavior, closed-market handling, illiquid wide-spread labeling, and resolution-rule risk (e.g., refund_50_50). This goes far beyond the annotations and provides crucial context for safe use.

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 section headers (RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK). The front-loaded purpose and usage are immediately clear. While some content may be more detailed than strictly necessary (e.g., exhaustive classifier list), it earns its place given 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?

With no output schema, the description must fully specify return semantics, and it does: result.market, result.analysis, result.evidence, parent_event, plus numerous edge cases. It explains blocking paths, tradeability flags, fallback behavior, and cancellation-rule impact. This is a complete picture for an agent to invoke and consume safely.

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

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

The schema already covers 100% of parameters with descriptions, giving a baseline of 3. The description adds extra nuance: the 'market' param is elaborated with examples of slug/URL/question forms; 'depth' is tied to fan-out counts ('quick = 2-3 evidence sources'); 'include_raw' is given a recommendation ('when false (recommended)') and explains size implications. This is meaningful added value, but much of it overlaps schema content.

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,' which is a specific verb-resource-action combination. It clearly differentiates from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on holistic bet research. The 'Use for' examples ('should I bet on X', etc.) further clarify its specific scope.

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

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

The description includes explicit 'Use for' directives and a rich set of fan-out examples that show when to apply the tool. However, it lacks explicit 'when-not-to-use' guidance or named alternative tools, so it doesn't fully meet the 'explicit exclusions/alternatives' bar.

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 rich behavioral details beyond annotations: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return format (paired data + pipeworx:// URIs). No contradictions with readOnlyHint or idempotentHint.

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

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

The description is somewhat long but every sentence adds value. It is front-loaded with trigger examples, then states the core function, data specifics, sorting, and output. A minor deduction for slight verbosity, but it remains well-structured and not wasteful.

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

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

Given there is no output schema, the description fully explains return behavior (paired data, citation URIs) and data sources. It also justifies efficiency (replaces 8–15 sequential lookups). For a tool with two parameters, this is comprehensive and leaves no critical gaps.

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

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

Schema coverage is 100%, so parameters are documented, but the description adds meaningful semantics: for company type it specifies the exact financial metrics pulled from latest 10-K, and for drug type it lists FAERS counts. It also clarifies the expected value formats (tickers/CIKs vs names) and the 2–5 range, enhancing schema info.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in a single parallel call, using specific verbs and resource types. It also distinguishes itself from sequential single-pack lookups, which sets it apart from sibling tools like entity_profile.

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

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

The description provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists trigger phrases like 'Compare X and Y' and 'rank these companies.' It does not explicitly name alternate tools for non-comparison cases, but the guidance is clear and actionable.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses account requirements, paid tier for thorough, latency expectations, the behavior of gaps[] (never invented), the guarantee that citation_uris are always fetchable, semantic excerpting, and contradictions[] results. This far exceeds what annotations alone convey.

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

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

The description is long but every sentence carries critical operational detail. It front-loads the account requirement and alternative tool before diving into mechanics. Minor redundancy exists (gap recovery described twice), but it remains well-structured and essential for such a complex tool.

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

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

Given the tool's complexity and the absence of an output schema, the description fully explains the return packet structure, gaps[], contradictions[], hop field, citation_uri, and latency, along with prerequisites and limitations. It leaves no significant contextual gap for an agent to misuse the tool.

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

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

The input schema already provides 100% coverage for both parameters, including detailed enumeration of depth levels and their semantics. The description adds some context (e.g., latency tied to depth, paid plan) but largely repeats what the schema already states, so baseline 3 is appropriate.

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

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

States clearly that it performs grounded multi-source research over Pipeworx's structured data sources in ONE call, decomposing questions into facets and routing to tools in parallel. It explicitly distinguishes from open-web search and from ask_pipeworx, and gives concrete examples of when it excels.

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: if not signed in, for single lookups, and for breaking/current-news topics, use ask_pipeworx instead. It also explains how depth levels map to research iterations, giving the agent clear selection criteria.

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=true and idempotent=true. The description adds valuable behavioral context beyond that: it returns top-N relevant tools with names, descriptions, and full input schemas (with curated examples), and says each result is ready to call directly with no second lookup. This sets accurate expectations for the output format and value.

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 efficient sentences: first states purpose, second specifies relevant domains and the return value, third gives usage guidance. The domain list is dense but necessary for search matching, and there is no filler or redundancy.

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

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

The description covers purpose, usage timing, return value, and output behavior. Since there is no output schema, the description compensates by describing the result structure (top-N, names, descriptions, schemas, examples). The tool is a discovery utility, and the description is complete for its complexity.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters (query plus four aliases) and limit with defaults/max. The description reinforces 'top-N' but does not add new parameter-level syntax or format details. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description uses a specific verb ('Find') and resource ('tools'), and clearly distinguishes itself as a meta-tool for discovery by naming the task types (browse/search/look up) and data domains. It stands apart from sibling tools that perform actual data retrieval tasks.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and gives a directive 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and a usage policy relative to alternatives.

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

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

Annotations already declare readOnly/OpenWorld/idempotent; description adds behavioral specifics: fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; returns specific fields with latest 10-K; patents API soft-fails; GDELT→GNews fallback. No contradiction with annotations.

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

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

The description is a single dense paragraph but front-loaded with trigger phrases and core purpose. All sentences contribute meaningful guidance (fallbacks, param constraints, return fields), though it could be broken into structured bullets for readability.

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

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

For a complex fan-out tool with no output schema, it lists all return components (cik, filings, fundamentals, patents, news, LEI) and caveats (patents sunset, names unsupported). Combined with strong annotations, an agent has enough to select and invoke correctly.

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

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

Schema covers both params at 100%, and description reinforces with concrete examples ('AAPL', '0000320193') plus zero-padded CIK requirement and name exclusion. This adds practical format guidance beyond schema, though not a lot more.

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

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

Description opens with trigger phrases and states 'full cross-source profile of a US public company in ONE parallel call.' It clearly names the resource (company) and action (profile), and distinguishes from sibling tools by explicitly saying to prefer it over chaining single-pack lookups.

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 signals via trigger phrases like 'Tell me about X' and 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' It also states when NOT to use: names are not supported, use resolve_entity first, thus guiding 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 destructiveHint=true and idempotentHint=true, so the description doesn't need to restate danger. It adds context by explaining what is deleted ('memory by key') and a use case ('clear sensitive data'), going slightly beyond the 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?

Three concise sentences, each adding value: purpose, usage triggers, and companion tools. Information is front-loaded and no filler exists.

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

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

For a single-parameter tool with full schema coverage and clear annotations, this description fully covers purpose, usage, and behavioral expectations. No output schema exists, but none is needed for a simple delete operation.

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

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

Schema coverage is 100% with a clear description ('Memory key to delete'), so the schema carries the parameter meaning. The description only adds 'by key' which doesn't materially enhance the schema's explanation.

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

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

The description uses a specific verb ('Delete') and clearly identifies the resource ('previously stored memory by key'). It distinguishes itself from sibling tools 'remember' and 'recall' by explicitly covering deletion, not storage or retrieval.

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

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

Provides explicit when-to-use conditions ('context is stale, task is done, clear sensitive data') and names companion tools ('Pair with remember and recall'), making the intended usage clear and differentiating from alternatives.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by detailing the behavior: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown format. This goes beyond the annotations and helps the agent understand the process and output.

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 main action. The first sentence conveys the core purpose and process, and the 'Useful for' list adds practical scenarios without unnecessary fluff. While slightly long, every sentence earns its place.

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

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

For a simple tool with only 2 parameters and no output schema, the description provides sufficient context: what it does, how it works, and what output to expect. It does not explain error handling or edge cases, but that is not critical for this straightforward generation task.

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

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

Schema description coverage is 100%, with both parameters (url, max_links) clearly described. The description adds little beyond the schema, only emphasizing 'any URL' and mentioning output format. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description clearly states the tool's purpose: 'Generate a production-ready llms.txt file for any URL'. It uses a specific verb (generate) and resource (llms.txt file), and explains the process (fetches, extracts, emits). This distinguishes it from sibling tools like ai_visibility_check, which focus on checking visibility rather than generating files.

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 offers 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.' It provides clear context for when to use the tool, though it does not mention specific alternatives or exclusions.

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

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

Annotations already provide read-only, idempotent, and non-destructive hints. The description adds value by specifying the exact information returned (fields with types, geometry type, record count, capabilities), giving the agent a clear picture of what to expect. It does not disclose potential errors or rate limits, but with strong annotations this is acceptable.

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 well-structured sentence that front-loads the action and resource, then lists the key data returned. Every word contributes value; there is no redundancy or filler.

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

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

With no output schema, the description adequately covers the return values by listing fields, geometry type, record count, and capabilities. For a single-parameter read-only tool with strong annotations, this is sufficient context for an agent to select and invoke the tool correctly. Minor gaps like error behavior are not critical here.

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 a clear description of the url parameter. The description confirms that the url is used to fetch the layer schema but adds no additional parameter-level semantics beyond what the schema already provides. 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 uses a specific verb 'Get' and names the exact resource: an ArcGIS Feature/Map Service layer's schema. It enumerates the returned attributes (fields, geometry type, record count, capabilities), making the tool's function unmistakable and differentiating it from siblings like query_layer which would fetch data rather than metadata.

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 the tool is for retrieving schema/metadata, but it does not explicitly state when to use this tool versus alternatives such as query_layer or search_within. No exclusions or alternative tool names are mentioned, so the usage guidance is only implicit.

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, covering the safety profile. The description adds useful behavioral context by specifying the return fields and the default scope ('active' subscriptions), which is not evident from annotations alone.

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

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

The description is two sentences long, front-loaded with the purpose, then lists return fields, and ends with usage guidance. No unnecessary words or repetition of schema details, making it highly efficient.

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

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

For a simple list tool with one optional parameter, no output schema, and strong annotations, the description adequately covers scope, return content, and typical use cases. An agent can confidently select and invoke this tool without further clarification.

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

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

The only parameter, include_inactive, is fully documented in the schema with a clear description and default value. The tool description does not add any additional semantic meaning beyond that, so the baseline score of 3 is appropriate given the 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 uses a specific verb 'List' and identifies the resource as 'the caller's active subscriptions', which clearly distinguishes it from sibling tools like subscribe/unsubscribe. It also enumerates the return fields, making the tool's function 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 explicitly suggests when to use the tool: 'review what you're monitoring before adding more or to find an id to cancel.' It does not mention alternative tools explicitly, but the context is clear enough for an agent to decide when this tool is appropriate.

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

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

Beyond annotations (readOnlyHint=false, etc.), the description discloses key behavioral traits: filing returns a claim_token for later status checks, rate limit of 5 per identifier per day, free/no quota impact, and daily team review. No contradiction with annotations; adds substantial context.

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

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

The description is longer than typical but every sentence carries necessary information. It is front-loaded with the core purpose, then flows logically through usage guidance, exclusions, workflow details, and rate limits. Slightly dense but not wasteful.

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

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

Given no output schema, the description fully covers return behavior (claim_token), parameters, usage context, exclusions, and operational details like rate limiting. The tool is non-trivial (4 params, nested objects) yet the description answers all likely agent questions.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra value by explaining the claim_token round-trip workflow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), clarifying the message length guidance, and contextualizing the type field via the earlier category enumeration. This raises above baseline.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates the feedback categories (bug, feature, data_gap, praise) and explicitly distinguishes from siblings by scoping only to Pipeworx tools, not other MCP servers.

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

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

Provides explicit when-to-use guidance (bug, feature, data_gap, praise) and a clear exclusion: do not use for tools from other MCP servers. Offers an alternative action ('file it with that server instead') and includes a test for uncertainty (tool names from this connection).

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

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

Despite favorable annotations (readOnly, idempotent, non-destructive), the description adds meaningful behavioral context: it states the data is self-aggregating, derived from an analytics engine, contains no PII, and has a cache TTL of 5min-1h. This goes well beyond the annotations and sets accurate expectations for freshness and sensitivity.

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

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

The description is compact and front-loaded with the core purpose. The 'Useful for' list is efficient, and the final sentence on data provenance/caching earns its place. The only slight deduction is for the mildly jargon-heavy phrase 'Self-aggregating signal,' but it is immediately clarified.

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

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

The tool is simplicity itself: one optional parameter, no output schema. The description covers the return values (top tools, packs, call volume), the window options, the use cases, and the data source/caching behavior. There are no significant gaps for an agent to get lost.

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?

With 100% schema description coverage, the baseline is 3. The description enhances this by elaborating on the window parameter: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds decision-useful semantics beyond the schema's simple enum.

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

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

The description opens with a specific, vivid statement ('What other AI agents are calling on Pipeworx right now') and explicitly lists the outputs: top tools, top packs, and total call volume. This clearly differentiates it from sibling tools like discover_tools, which likely focuses on discovery rather than usage trends.

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

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

The 'Useful for' section enumerates three concrete scenarios, providing clear context for when to invoke this tool. It also explains window semantics to guide parameter choice. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral context: Jaccard similarity threshold (≥0.30), placeholder-slug filtering, partition-check deviation threshold (>3pp), and the fill-check pricing process (theoretical vs realizable edge at 1000 shares/leg). It even warns not to trade when realizable_edge_pp ≤ 0. This goes well beyond the structured annotations.

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

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

The description is long but densely packed with valuable directives, examples, and caveats. It is front-loaded with the primary purpose and uses capitalized section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to aid scanning. A few sentences could be trimmed, but nothing feels extraneous.

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, but the description compensates by specifying the response shape: opportunities[] with fields like gap_pp, suggested_trade, reasoning, and partition_check details. It covers edge cases (placeholder filters, low-similarity skips, fill-check overround) and points to polymarket_fill_risk for sizing, making the tool fully usable with the information provided.

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

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

The input schema already provides full descriptions and 100% coverage for both parameters. The description adds extra meaning with concrete slug examples, URL acceptance, mode recommendations ('recommended for a specific market'), and behavior details like 'walks child markets' and 'searches related events', making the parameters more actionable than the schema alone.

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

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

The description opens with a specific action ('Find arbitrage opportunities on Polymarket') and the method ('monotonicity violations + partition-sum checks'), clearly distinguishing it from generic search or monitoring tools. It also contrasts with sibling polymarket_fill_risk by mentioning custom sizing, reinforcing its role as the arbitrage-detection tool.

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 for each parameter mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)', with examples and trade-offs like 'Cross-event mode catches patterns that single-event misses.' It also points to polymarket_fill_risk for custom sizing, though it does not explicitly discuss alternatives like polymarket_edges or polymarket_edge_tracker.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description extensively discloses behavioral details: per-leg slippage handling, Kelly fraction capping at 0.25, the 24h-move warning ('your edge may already be in the price'), placeholder-slug filtering, partition-level kelly_fraction_half=0 by design, and KV-level 1h caching keyed on all knobs. It even reveals diagnostic structures like _diagnostics with funnel counters so callers understand why segments may be empty. This is exemplary transparency.

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

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

The description is long but well-structured with clear section breaks (TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and front-loads the core purpose. Most sentences carry valuable information—e.g., the detailed model family definitions and the 'rare-by-design' note for concentrated longshots. It is not maximally concise, and the density may overwhelm quick scanning, but it earns its length for a tool of this 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?

Despite lacking an output schema, the description thoroughly documents the response structure: by_segment{model_driven,structural_arbitrage,concentrated_longshot}, fed_candidates/fed_note, and _diagnostics. It also explains what each opportunity carries (edge_pp_net, kelly_fraction, market.liquidity, etc.) and why certain gates exist (placeholder-slug filter, 25:1 portfolio return). The tool has 9 parameters and no output schema; this description provides enough context for an agent to confidently invoke it 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?

Even though the schema covers 100% of parameters, the description adds substantial meaning beyond field names. It explains that min_partition_leg_kelly applies to per-leg Kelly inside top_legs, not parent-level kelly_fraction_half, and that partition arbs always return parent kelly_fraction_half=0. It also explains the rationale for slippage_pp (zero fees but bid/ask eats 20-50bp) and the tradeable-edge knobs' purpose ('drop opportunities where edge isn't realizable'). This goes far beyond the schema's per-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 first sentence states a specific verb ('Scan'), resource ('top Polymarket markets'), and outcome ('return opportunities where Pipeworx data disagrees with market price'). It further distinguishes this tool from siblings by detailing three concrete opportunity segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) with model names and formulas, making it unmistakably unique.

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

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

The description explicitly says the tool is 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also gives concrete knob usage ('min_liquidity / max_spread_pp drop opportunities where edge isn't realizable') and mentions that Fed candidates are excluded because '1m-T vs EFFR signal is unreliable at meeting-month horizons.' However, it does not explicitly name alternative tools or when-not-to-use scenarios beyond Fed bets, 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), the description discloses meaningful behavioral details: snapshots are written on cache-miss, gaps in snapshot_dates mean nobody scanned, history depth is bounded by a 60-day TTL, and decay numbers are based on daily closes rather than intraday data. It also explains exactly what tracked[] and expired[] represent, giving the agent a clear picture of data semantics 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 lengthy but well-structured into ARGS, RESPONSE, and LIMITS sections, with each sentence carrying substantive information. However, it could be more scannable with bullets or brevity; the core purpose could be stated more succinctly. It is appropriately sized for the tool's complexity, but slightly dense.

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

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

Given there is no output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and the meaning of decay/trend fields. It also addresses edge cases like expired opportunities, data gaps, and TTL limits, making it complete for an agent to use the tool correctly.

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

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

The schema already covers both parameters with descriptions (e.g., days default 14 clamp 2-30, window family options). The tool description adds only minimal extra context—'snapshot family' for window and 'lookback' for days—which does not significantly go beyond the schema. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description opens with a specific verb phrase 'Edge persistence and decay telemetry' and clearly answers the question 'how long has this edge existed and is it shrinking?', which distinguishes it from sibling tools like polymarket_edges that likely report current edges. It also adds context comparing fresh versus old edges, reinforcing its unique 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 tool explains its intended use by contrasting a fresh wide edge with a 3-week-old edge, implying it should be used to assess edge persistence before acting. It does not explicitly name an alternative like 'use polymarket_edges for current edges', so it stops short of full when-to-use vs. when-not-to-use guidance.

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

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

Annotations already mark the tool read-only/idempotent, and the description adds valuable behavioral detail: it walks the order-book ladder, returns verdicts (clean|degraded|cannot_fill), exposes thin_legs and forced_directional_risk, and warns about partial-fill exposure turning arb into directional position. 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 structured into clear mode blocks (SINGLE-MARKET/BASKET) with a front-loaded summary and a crisp 'USE THIS' callout. It is long, but every block adds necessary detail for a dual-mode tool; could be slightly tighter around repeated size 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 enumerates key return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk). It also covers both parameter modes and gives rationale, making it effectively self-contained for the 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?

Input schema has 100% parameter coverage with detailed descriptions for side, event, market, and size_usd. The tool description reinforces and clarifies the semantics, especially the mode requirement (requires one of market or event) and size_usd interpretations for buys vs sells and basket settlement notional, adding modest 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?

Description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' a specific verb+resource framing that clearly separates it from pure arbitrage detection siblings. It distinguishes single-market and basket modes explicitly, and references sibling tools (polymarket_arbitrage, polymarket_edges) in the usage guidance, making its unique role unmistakable.

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

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

Explicit 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' provides a clear trigger condition. It also explains why (theoretical overround on thin books not capturable) and identifies the risk of partial fills, giving the agent decision rules.

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 openWorldHint=true, but the description adds extensive behavioral context: compatibility_warning semantics, temporal_alignment implications ('aligned:false means spreads are mathematically meaningless'), and skip counters. It discloses that most pre-mapped topics currently return warnings, setting accurate expectations beyond what annotations convey.

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

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

The description is a single dense paragraph but organized into labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). It is front-loaded with the core purpose and contains no filler, though it is long. Some structure with bullets would improve scannability, but every sentence carries 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?

Given no output schema, the description takes responsibility for explaining return values: leg-by-leg prices, matched spread top_spreads_pp, compatibility_warning cases, temporal_alignment, and skip counters. It covers the main usage branches and failure modes, though the exact nested structure of the response could be more explicit. Overall, it is thorough 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?

Schema already documents all three parameters with descriptions (100% coverage), so baseline is 3. The description adds meaning by explaining the relationship between parameters: topic as a shortcut vs kalshi_event_ticker/polymarket_event_slug as explicit overrides, and how they interrelate. This elevates it above baseline.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', a specific verb+resource+scope statement. It clearly distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison and explicitly names two modes (topic shortcuts vs explicit tickers).

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 two modes of invocation and clarifies that explicit tickers override topic-mapped sides. It provides crucial caveats about when spreads are meaningful ('when the bet shapes are equivalent') and warns that pre-mapped topics often return compatibility warnings and are not necessarily tradeable, guiding appropriate usage.

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

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

The annotations already declare readOnly, openWorld, and idempotent hints, so the safety profile is covered. The description adds useful behavioral detail: it returns attribute rows and geometry, and recommends a sampling pattern. It does not discuss rate limits or error behavior, but annotations lower the bar.

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, information-dense sentence plus one practical tip. It is front-loaded with the tool's purpose and contains no filler, making it highly efficient.

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

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

For a query tool with six parameters and no output schema, the description covers the core purpose, URL source, and return content (rows and geometry). It also gives a concrete usage example. Missing details like pagination nuances or error handling are partially covered by the schema's offset description, so it is reasonably complete.

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

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

Schema coverage is 100%, with each parameter described in the input schema. The description repeats parameter names and adds phrases like 'SQL-like' and 'comma-separated', but those details are also present in the schema. It provides no additional semantic meaning beyond what the schema already documents.

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 ('Query') and the resource ('ArcGIS Feature Service / Map Service layer'), specifies the URL source ('from search_datasets'), and lists key parameters (where, out_fields, order_by, limit, offset) and output (attribute rows and geometry). This distinguishes it from siblings like layer_info or search_datasets.

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

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

Guidance is implied by instructing to use a URL from search_datasets and by suggesting a sampling technique. This provides clear context for when to use the tool but does not explicitly mention exclusions or alternative tools, so it falls short of a 5.

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

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

The annotations already declare readOnlyHint and idempotentHint, and the description adds valuable context about scoping: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)'. This goes beyond the annotations, though it doesn't cover error cases or return format details.

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 main action, and every phrase adds value: it covers behavior, examples, scoping, and related tools without wordiness.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description is complete: it explains the return behavior (value or list of keys), the scoping, and how it relates to remember/forget. Annotations cover safety, so no 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?

The schema covers 100% of parameters with descriptions, so baseline is 3. The description adds semantic context by explaining that omitting the key lists all keys and that keys refer to values 'previously saved via remember', which reinforces the schema 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 states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys'. It identifies a specific verb and resource, and distinguishes itself from siblings by explicitly referencing 'remember' and 'forget'.

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

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

It provides explicit usage context: 'Use to look up context the agent stored earlier' and gives concrete examples. It also names the companion tools for saving and deleting, giving clear when-to-use and alternatives.

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

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

The description contradicts the annotations. It says 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which implies a persistent state change, yet the annotations declare readOnlyHint:true and idempotentHint:true. This is a serious inconsistency that could mislead an agent about side effects.

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

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

The description is concise and front-loaded: it starts with the main action, then covers return content, filtering, the key behavioral option, and an alternative access method. Every sentence earns its place with no redundancy or padding.

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

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

Given the tool has 5 parameters and no output schema, the description covers return format, filtering, mark_read behavior, polling suitability, and an alternative endpoint. It lacks some details (e.g., interaction between mark_read and unread_only, pagination), but is largely complete for a read-oriented tool. The annotation contradiction slightly undermines completeness.

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

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

The input schema covers all parameters (100% coverage), so a baseline of 3 applies. The description adds value by explaining the purpose of mark_read ('so the next call only shows newer ones') and gives a concrete example for type ('sec_8k'), going beyond the schema's minimal descriptions.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed' and specifies the return contents (source, citation_uri, raw event payload). This distinguishes it from sibling tools that manage subscriptions or show changes, making the purpose unambiguous.

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

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

The description provides clear usage context: filtering by type and since, using mark_read for read tracking, and notes that polling works fine. It also offers an alternative HTTP endpoint for scripts/dashboards, but does not explicitly mention when to prefer this tool over sibling tools like recent_changes or list_subscriptions.

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

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

The description goes beyond the readOnly/openWorld/idempotent annotations by disclosing the specific external APIs (SEC EDGAR, GDELT→GNews fallback, USPTO) and their failure modes (GNews when rate-limited, USPTO soft-fail after May 2025). It also specifies the return structure, including grouped changes and citation URIs, which is valuable behavioral context.

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

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

The description is front-loaded with example queries and a clear statement of scope, then efficiently details fan-out sources, parameter syntax, return structure, and alternatives in about 110 words. Every sentence provides useful information without redundancy, making it appropriately dense 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?

Despite lacking an output schema, the description explains the return format (changes[] grouped by source, total_changes count, citation URIs) and covers external dependencies and fallback behavior. It could mention edge cases like empty results or rate limits on the tool itself, but overall it gives an agent sufficient context to select and invoke the tool correctly.

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

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

The input schema already provides comprehensive descriptions for all three parameters (type enum, since format, value formats), covering 100% of the schema. The description reinforces these with examples and suggests '30d' or '1m' for typical monitoring, but does not add substantive semantic meaning beyond the schema.

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

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

The description clearly defines the tool as a change feed for a company over a specified window, listing concrete query examples and the sources it fans out to. It explicitly distinguishes itself from entity_profile, which provides static profiles, making its scope immediately clear.

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 by listing natural-language triggers ('What's new with X') and stating it handles the last N days/weeks/months in one parallel call. It also gives an explicit alternative: use entity_profile for static profiles, clarifying when not to use this tool.

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

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

Annotations already signal nontrivial behavior (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds valuable context beyond annotations: storage mechanism ('key-value pair scoped by your identifier') and persistence duration (authenticated vs anonymous sessions). This is meaningful but not exhaustive (e.g., no mention of overwriting behavior beyond idempotency).

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 carrying distinct information: purpose, when to use, storage mechanics, and pairings. No redundancy, no filler. The front-loaded verb 'Save' immediately communicates action.

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

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

For a simple two-parameter write tool with no output schema, the description is fully adequate. It covers what the tool does, when to use it, persistence behavior, and how it relates to recall and forget. No critical gaps remain for an agent to invoke it correctly.

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

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

Schema description coverage is 100%: both parameters (key, value) are already documented with types and examples. The description adds marginal value by framing them as a key-value pair and noting the identifier scoping, but it doesn't meaningfully extend the schema's clarity. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly differentiates from siblings by naming recall and forget as complementary tools, and the scope ('across this conversation or across sessions') adds precision.

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

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

It explicitly states when to use the tool: 'Use when you discover something worth carrying forward...' and provides alternatives: 'Pair with recall to retrieve later, forget to delete.' This gives the agent clear decision criteria.

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. The description adds valuable behavioral context: every identifier is source-labeled, unresolved identifiers are explicitly stated under 'unresolved', graceful degradation when GLEIF/OpenFIGI are unavailable, and the fact that each call cascades through several endpoints. This goes well beyond annotations and informs the agent about output structure and failure modes.

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

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

The description is long but every sentence earns its place. It front-loads with user-language examples, then organizes details by supported type, output labeling, source attribution, and degradation behavior. The structure is logical and dense with relevant information, making it easy for an agent to quickly grasp the tool's scope and behavior.

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

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

Given there is no output schema, the description compensates well by detailing what identifiers are returned (CIK, ticker, LEI, FIGI, RxCUI), how they are labeled, and how unresolved cases are handled. It covers input formats, internal cascading, and degradation. This is complete for a lookup tool of this complexity.

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

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

The input schema already provides 100% coverage with descriptions for both parameters. The description reinforces this with specific examples (AAPL, 0000320193, 'ozempic') and adds nuance like 'ticker implied' for FIGI resolution. While it doesn't fundamentally change parameter meanings, the examples and contextual notes add 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 concrete example queries and then states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' This is a specific verb+resource+outcome, and it clearly distinguishes the tool from siblings by positioning it as the go-to for name-to-ID lookups.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' It also explains the supported entity types and what each returns, giving clear context for when to use it. It does not explicitly mention when not to use it or alternatives, but the directive 'Use FIRST' implies a primary use case, so the lack of exclusions is a minor gap.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral detail: it 'Probes each entity with ai_visibility_check', 'ranks by score', and 'Returns ranked list with score, confidence, signal density per entity.' This goes beyond the annotations and gives clear expectations, 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 three sentences, front-loaded with purpose, then method, then use case and output. Every sentence contributes value, with no filler or redundancy.

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

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

Despite lacking an output schema, the description specifies the return format ('ranked list with score, confidence, signal density per entity'). It covers purpose, method, usage context, and output, making it complete for a read-only comparison tool.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema; it does not mention the 'models', '_apiKey', or 'context' parameters. All parameter semantics are already fully detailed in the input schema descriptions.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side' – a specific verb and resource. It distinguishes itself from the sibling tool ai_visibility_check by emphasizing multi-entity comparison and ranking, not single-entity checks.

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

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

The description provides a clear usage context: 'Useful for competitive AI-marketing audits' and gives a concrete example. It implies this is for comparing multiple entities vs. a single-entity check, but it does not explicitly name alternatives or exclusions.

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

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

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds valuable behavioral context: it fans out to external services, can take 5–30s on first bundlephobia measurement, degrades gracefully with sources_failed, and is scoped to NPM. This goes well beyond the annotation 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 dense but well-structured, front-loading the core value ('Composite... check in ONE call') and then efficiently covering sources, use cases, return fields, constraints, and failure modes. Every sentence adds practical information with no fluff.

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

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

With no output schema, the description thoroughly explains the return format: summary block fields, per-advisory detail, links, alternative versions, and partial failure handling. It also covers ecosystem limitations and timing behavior, making the tool fully understandable in context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does mention NPM-only scope and that version defaults to latest, but those are already captured in the input schema. It adds no new parameter-level detail beyond the schema.

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

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

The description opens with a clear, specific purpose: a composite 'should I add this npm package' check. It names the exact data sources (deps.dev and bundlephobia) and what it aggregates (license, advisories, version history, bundle size, dependency count, ESM/tree-shake support), making it highly distinguishable from the sibling tools.

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

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

The description explicitly states when to use the tool: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives exclusions and alternatives—'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'—and clarifies partial failure behavior.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context by specifying the exact returned fields (name, summary, record_count, owner/org, URL) and notes that org_id can override the default org. 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?

Two sentences, front-loaded with the primary purpose, then concise return-value details. No wasted words; every phrase adds information.

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

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

For a simple search tool with only 3 optional parameters and no output schema, the description adequately covers what it returns, its scope, and how to use the results with sibling tools. It is complete without being verbose.

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 parameters are already well-documented in the schema. The description does not add extra parameter semantics beyond reinforcing 'by keyword' and the URL pass-through, but it doesn't need to.

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 names the resource ('City of Roanoke GIS open geospatial datasets') with examples (parcels, zoning). It clearly distinguishes from siblings by mentioning query_layer / layer_info as the follow-up 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 to search by keyword and then 'pass that url to query_layer / layer_info', providing a clear workflow and alternatives. This tells the agent when to use this tool and how it fits into a broader process.

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 the read-only, open-world, and idempotent nature. The description adds valuable behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, the 200K char cap with truncation and flagging, and the output structure. These go beyond the annotations and give the agent a precise mental model of tool 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 three sentences long but packs substantial information: core purpose, usage scenario, integration with a sibling, algorithm details, limits, and output. It is front-loaded with the primary action and every sentence earns its place; no filler or redundancy.

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

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

Although there is no output schema, the description clearly states the return type: 'top-N passages with character offsets and similarity scores.' It also discloses edge cases (truncation flag), technical limitations, and tool relationships. For a search tool with strong annotations, this description is fully complete.

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

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

Schema description coverage is 100%, so all parameters (text, query, limit) are already documented in the schema. The description adds contextual meaning such as 'top-N passages' for limit and example queries for query, but this is marginal beyond the schema. With high schema coverage, 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 'Semantic search INSIDE a fetched record,' a specific verb+resource combination. It further distinguishes from siblings by specifying the input is 'text you already pulled' and explicitly calls out the use case for records too big for the prompt, which clearly separates it from tools like ask_pipeworx_grounded.

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

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

The description gives an explicit usage condition: 'Use when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter.' It also names a complementary workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document,' providing clear when and how to use the tool relative to a sibling.

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

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

The description goes far beyond the annotations by disclosing OAuth requirement, persistence rules, phone verification, per-day SMS cap, webhook HMAC signing, delivery of a one-time signing secret, and auto-disable after 10 consecutive failures. These details give the agent a thorough understanding of side effects and operational 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 dense paragraph that covers types, delivery channels, and constraints without excessive verbosity. Every sentence earns its place, though the density could be slightly improved with bullet points or clearer segmentation. 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?

Given the complexity (5 types, nested delivery object, no output schema), the description comprehensively addresses the subscription creation process: supported types with examples, delivery options, authentication requirements, and how to pull from the persistent feed. No critical usage information is missing.

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

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

Schema description coverage is 100% and the schema already provides detailed parameter descriptions, including exact JSON shapes and examples. The tool description repeats much of this information without adding new parameter-level semantics, so the baseline of 3 applies due to the 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 opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream' and states it returns a new subscription id. It clearly distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on the creation action and listing supported 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?

The description implies when to use the tool (to set up monitoring) and provides clear constraints, such as requiring a Pipeworx OAuth account and noting that anonymous/BYO cannot persist. It also explains delivery channel options and prerequisites like phone verification. However, it doesn't explicitly discuss alternatives or when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations by describing what the tool returns (category-bucketed example questions with exact tool+argument shapes) and the optional topic behavior. It does not contradict annotations and provides sufficient transparency about its read-only, discovery-oriented nature.

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 leading example phrases and a clear breakdown. It front-loads the purpose and usage, then provides details on return contents and topic parameter. Some repetition in the example phrases could be trimmed, but each sentence earns its place by clarifying the tool's value proposition.

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 purpose as an onboarding guide, the description covers all necessary context: what it returns, how to call it (with/without topic), when to use it first, and its relationship to meta-tools. Even without an output schema, the description sufficiently explains the return format and provides enough detail for effective selection and invocation.

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

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

Schema coverage is 100%, so the parameter is documented. The description adds extra meaning by giving concrete topic examples ('finance', 'pharma', 'betting') and explaining the default behavior when omitted ('cross-category spread'). This goes beyond the schema's enumeration by clarifying expected values and default behavior.

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 is the onboarding entry point for suggesting questions and returns category-bucketed example questions with tool mappings. It uses specific verbs (suggest, returns) and explicitly distinguishes its role from meta-tools by positioning it as the FIRST tool to use when unfamiliar with Pipeworx capabilities.

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

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

Explicit usage guidance is provided: 'Use this 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 call with no arguments for full spread or pass a topic, giving clear context for when and how to use the 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 adds meaningful behavioral context beyond the annotations: ownership enforcement ('you can only cancel your own subscriptions') and the soft-delete mechanism ('deactivated not deleted'), ensuring the agent understands side effects. No contradiction with annotations.

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

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

The description is three sentences, each with a distinct purpose: the action, the ownership constraint, and the behavioral side effect. It is front-loaded with the verb and contains no fluff.

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

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

With one parameter and rich annotations (destructive, idempotent hints), the description covers ownership, deactivation, and the link to recent_alerts. It doesn't mention return values, but the tool's low complexity makes this acceptable.

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

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

The input schema already describes the single parameter 'id' as a uuid returned by subscribe, covering 100% of its semantics. The description doesn't add further meaning to the parameter itself, so baseline 3 applies.

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

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

The description uses a specific verb 'cancel' and clearly identifies the resource ('subscription by id'). It also distinguishes the tool from siblings by noting the deactivation behavior (not deletion), which is unique among related tools like subscribe and list_subscriptions.

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

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

The description implies when to use the tool (cancel a subscription you own) and references recent_alerts as an alternative for viewing historical events, providing contextual guidance. However, it doesn't explicitly contrast with subscribe or list_subscriptions.

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

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

The description discloses extensive behavioral traits beyond annotations: the two-path processing, the exact verdict set, the special meaning of 'could_not_verify' (check did not happen, not evidence) and 'unsupported' (no source exists), and the return of citations with reasoning. It does not contradict the readOnly/openWorld/idempotent annotations; instead it adds critical nuance about failure modes and result interpretation.

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

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

The description is long but highly structured: it opens with trigger phrases, then states the use case, explains the two verification pipelines, lists the verdicts, and closes with important caller caveats and efficiency benefits. Every sentence provides necessary information, so it is not bloated, though it is lengthy for a tool description.

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

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

Given the tool's complexity (two pipelines, six verdicts, error handling), the description covers everything needed for correct invocation: when to use, what to expect, how to interpret ambiguous verdicts, and why it is more efficient than sequential calls. It adequately describes all return semantics and edge cases, even without an output schema.

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

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

Schema coverage is 100%, and the description repeats the parameter descriptions almost verbatim (e.g., tolerance behavior, default capping at 5). The claim examples in the description mirror those in the schema, adding no new meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description identifies a specific verb ('verify'/'fact check') and a specific resource: natural-language claim verification against authoritative sources. It clearly distinguishes itself from sibling tools by focusing on fact-checking and even describes the two distinct pipelines (SEC EDGAR for company-financial claims, grounded pipeline for other claims), making its 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear context. It does not explicitly name alternative tools or when not to use it, but it does imply that it replaces multi-step sequential lookups, giving a strong sense of when it is appropriate.

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