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 cover read-only, open-world, idempotent, and non-destructive traits, lowering the burden. The description adds genuine context beyond those annotations: routing across 5,743 tools and 1,500 sources, stable pipeworx:// citation URIs, 'one fast call', works on every tier, and live-news routing. It doesn't fully describe failure modes or exact answer shape, but the added behavioral value is clear and consistent with annotations.

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

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

The description is long but front-loaded with the most important guidance ('PREFER OVER WEB SEARCH' and 'START HERE') before covering routing, alternatives, and examples. Every sentence contributes operational guidance, though a few redundancies around 'ask_pipeworx' and the examples block make it slightly denser than necessary. Still well-organized and easy to scan.

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

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

There is no output schema, so the description carries the burden of explaining what the agent can expect. It does state 'returns the structured answer with stable pipeworx:// citation URIs' and gives extensive domain coverage and usage conditions. It stops short of detailing the answer's JSON shape or citation format, but the combination of examples, alternatives, and behavioral context is sufficient for a capable agent to select and invoke this tool correctly.

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

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

Schema coverage is 100%, with all aliases documented, so the baseline is 3. The description adds value above the schema by providing realistic example questions ('current US unemployment rate', 'Apple's latest 10-K', 'active clinical trials for GLP-1') and clarifying the question should be natural-language and factual, which helps an agent construct effective inputs.

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 names a specific function — routing natural-language questions to one of 5,743 tools and returning structured answers with citation URIs — and distinguishes itself from siblings ask_pipeworx_grounded and deep_research. The examples and 'START HERE' phrasing make its role as the default factual-question entry point 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?

Explicitly says 'PREFER OVER WEB SEARCH' and 'Use whenever' with concrete trigger phrasing ('what is', 'look up', 'find', 'get the latest'). It also tells the agent when to step up to alternatives: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions, plus a breaking-news exception. This is exactly the when-to-use vs. alternatives guidance expected.

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

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

Beyond the annotations, the description discloses that this is an experimental edge, that candidate routing improvements are enabled live, and that it is a fully working router that does not fall back to anything. The current status of no active candidate is also transparently stated, which is valuable behavioral context beyond the readOnly/idempotent hints.

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

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

The description is information-dense without being bloated. Each sentence adds distinct value: beta definition, current identical state, usage instruction, and a clarification that it is a full working router. It is well-structured and front-loaded with the core purpose.

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

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

For a router with no output schema, the description compensates by explicitly stating that the response shape is identical to ask_pipeworx and that arguments are the same. Combined with full schema coverage and the experimental-status explanation, an agent has everything needed to invoke the tool correctly.

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

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

Schema description coverage is 100% and every alias is already documented. The description adds no new parameter-level meaning beyond stating that arguments are identical to ask_pipeworx, so it does not raise the score above the baseline.

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

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

The description clearly identifies the tool as a beta variant of ask_pipeworx, a universal router with the same 5,743 tools, arguments, and response shape. It also distinguishes it from the stable ask_pipeworx by noting the experimental routing improvements, so an agent can understand exactly what this tool is and how it relates to siblings.

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

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

The description explicitly states to use it exactly like ask_pipeworx when the newest routing is desired, and notes that results are compared against the stable router. It gives clear situational context, including that no candidate is active right now so it matches ask_pipeworx exactly, which tells the agent when and how to use it.

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

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

Annotations already mark readOnly/openWorld/idempotent, but the description adds substantial behavior beyond that: the return shape {answer, evidence, confidence, source, fetched_at, refusal_reason:null}, the explicit refusal mechanism with specific refusal_reason values, and the constraint that the answer is extracted 'using ONLY what the tool result contains'. It also discloses the extra LLM call cost and does not contradict annotations.

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

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

The description is dense but each sentence carries purpose: first the core value proposition, then the return/refusal contract, then clear usage guidance and cost tradeoff. The phrase 'Same routing as ask_pipeworx — picks the right tool from 5,743 across 1500 sources, fills arguments, fetches the data' is slightly verbose but reinforces the behavior without 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?

Despite having no output schema, the description covers both success and failure outcomes in detail, including every refusal_reason enum value. For a tool with a single required parameter and rich annotations, nothing an agent needs to invoke it correctly or interpret its results is missing. The tradeoff vs ask_pipeworx is clearly stated.

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 all six parameters are aliases for the same natural-language 'question'. The description does not add much beyond what the schema already provides for parameters, but it does clarify that the question will be routed through the same tool-selection pipeline as ask_pipeworx. This is adequate for a single-logical-parameter tool, so the 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 states a specific verb-resource combination: 'Hallucination-resistant answer mode for high-stakes reads' and clearly distinguishes it from ask_pipeworx by describing the extraction-only-answer behavior. It also explicitly names its sibling 'ask_pipeworx' as the same routing but without the grounded extraction, so an agent can tell them apart without opening schemas.

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

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

It gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete scenarios like 'financial verdicts, legal claims, medical lookups, public statements'. It also provides a clear when-not-to-use: 'prefer ask_pipeworx for casual lookups', citing the extra LLM call cost. This fully routes the agent to the correct 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?

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 annotations (read-only, open-world, idempotent, non-destructive), the description discloses auth/plan requirements, parallel decomposition, output packet shape, gaps[]/contradictions[] fields, citation resolvability, semantic excerpting, and latency. No annotation is contradicted; the description substantially enriches the safety/behavior picture.

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

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

The description is long, but the tool is complex and nearly every sentence adds actionable context (auth, fallback, output, gaps, latency). It loses the top score because it repeats some schema detail (e.g., depth hop counts) and fronts the account requirement before stating the core purpose.

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

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

With no output schema, the description fully documents what the agent can expect: findings packet fields, citation URI semantics, gaps[], contradictions[], hop field, excerpting behavior, and latency. It also covers the account prerequisite and the alternative tools, leaving no material gap for correct invocation.

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

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

Schema description coverage is 100%: the schema already defines question as natural-language broad/multi-part and describes each depth value including facets, gap-recovery, contradictions, and paid tier. The description adds examples and usage framing but mostly restates or supplements the same meaning, so it stays at the baseline for high schema coverage.

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

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

The description names the specific operation ('grounded multi-source research ... in ONE call'), states the resource (Pipeworx's 1500 structured data sources), and explicitly distinguishes itself from open-web search and from ask_pipeworx. It also gives representative question types, so an agent can identify when this tool applies.

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

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

It gives explicit 'best for' conditions (broad/multi-part structured questions), explicit exclusions ('single lookup use ask_pipeworx'), and current-news guidance with the exact failure mode (empty gaps[]). It even names the fallback tool for unsigned-in users. This is unusually complete routing guidance.

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

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

Annotations already declare readOnly=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 mark the tool read-only and idempotent, and the description adds substantial behavioral context: parallel fan-out across sources, sources_used/sources_failed semantics, empty sections meaning real absence of data, private-company resolved:false behavior, and USPTO API sunset soft-fail. This far exceeds the annotation baseline with no contradictions.

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

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

The description is front-loaded with triggers and the core directive, then densely packs source and return information. It is information-dense and mostly earns its length, but it runs as one long semicolon-heavy paragraph and partially duplicates parameter semantics already present in the schema.

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

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

With no output schema, the description carries the full burden of explaining return values and edge cases, and it does so comprehensively: each output section is named, source-specific caveats are provided, and failure/empty states are explicitly handled. Nothing an agent needs to invoke this complex tool correctly appears to be 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?

Input schema coverage is 100% and already documents both parameters well, giving a baseline of 3. The description adds helpful concrete examples (ticker 'AAPL', CIK '0000320193', name 'Moderna'), clarifies that type values behave identically, and notes future person/place support, but much of this is corroboration rather than entirely new parameter meaning.

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

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

The description clearly identifies the tool as a full cross-source profile for US public companies, with example queries and the key phrase 'full cross-source profile ... in ONE parallel call.' It is specific about the resource and scope, but it does not explicitly name sibling tools like resolve_entity or compare_entities to differentiate them, so it stops short of a 5.

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

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

It gives explicit triggering conditions ('Tell me about X', 'brief me on Tesla', 'when the user asks for a holistic view') and an explicit preference directive: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' This tells an agent exactly when to select this tool and what to favor it over, which is strong usage guidance.

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

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

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 indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description goes far beyond: it discloses compatibility codes, unclassified legs never being paired, pairing_unverified always being set, fees_note stating gross spreads with unmodeled Kalshi fees, skipped counters, and temporal_alignment null semantics. 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 very long and dense, with multiple parenthetical clarifications and technical caveats. It is front-loaded with purpose and every section contains useful information, but the wall-of-text format could be better organized into bullets or structured sections. It earns its length factually but is not concise.

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

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

There is no output schema, so the description must explain return structure and edge cases. It does so thoroughly: leg-by-leg prices, top_spreads_pp with per-entry flags, compatibility_warning/codes, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and skipped counters. An agent has everything needed to interpret the response correctly.

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

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

Schema coverage is 100% with topic enum values and examples. The description adds mode semantics: topic auto-fetches the matching event, explicit tickers/slugs override the mapped side, and both modes run the identical matcher. This is meaningful value beyond the schema, though the schema already carries the parameter list and examples.

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

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

The description clearly states the tool computes the spread between Kalshi and Polymarket for the same resolving question, with a specific verb and resource. It details two modes and distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue Kalshi–Polymarket spreads. The purpose is unambiguous and differentiated.

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

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

The description clearly explains when to use each mode: topic shortcuts for pre-mapped macros and explicit ticker/slug pairings for custom events. It also warns that pre-mapped topics often return compatibility warnings and that 'pre-mapped ≠ tradeable'. However, it does not explicitly compare against sibling tools or state when not to use this tool, so it misses the top tier.

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?

The description goes far beyond the annotations by disclosing detailed behaviors: graceful degradation if GLEIF/OpenFIGI is unavailable, assertion of nothing and return of figi_candidates when ambiguous, explicit listing of unresolved identifiers under 'unresolved', and internal cascading through lookups. These are valuable behavioral traits not inferable from 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 long but information-dense; each sentence adds locally relevant context for a complex entity-resolving tool. It is front-loaded with examples and high-level purpose, then details. While some redundancy exists (e.g., repeated mentions of FIGI), overall it earns its length given the tool's complexity, but it could be tightened slightly without losing value.

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

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

The description fully covers what an agent needs to know to call the tool correctly: input formats, supported types, behavioral on ambiguity, graceful degradation, and how different identifiers are sourced. Since there is no output schema, the description adequately explains return-like concepts (figi_candidates, unresolved), and annotations already cover safety. Nothing critical is missing.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema. For the 'value' parameter, it provides crucial guidance about passing only the entity name and warns against including security-class words like 'revenue bonds' with a concrete example. It also explains how ISIN input resolves via the GLEIF mapping, enriching the semantics beyond the schema's brief text.

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 that the tool resolves a user-spoken name to canonical/official identifiers, which is a specific verb and resource. It enumerates the supported types (company, drug) and explicitly mentions cross-source identifiers (CIK, ticker, LEI, FIGI, RxCUI), distinguishing it from siblings. It also notes the specific use case of resolving names to IDs that other tools require.

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', which is clear when-to-use guidance. It also explains that it replaces multiple manual lookups. However, it does not explicitly mention when not to use it or name alternative sibling tools (like entity_profile) for other purposes, so it lacks full when-not/alternatives coverage.

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.