Arcgis Durham

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context: the default model is free, and providing `_apiKey` triggers calls to Anthropic with direct billing to the user ('you pay Anthropic directly'). It also discloses the return structure. This goes 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?

The description is compact and well-structured. It leads with the core purpose, then covers configuration and return format, and ends with use cases. Every sentence provides useful information without redundancy, 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?

Given the tool's moderate complexity (4 parameters, no output schema), the description adequately covers the response format and key behaviors. It explains default behavior, optional configuration, and typical applications. It does not detail error handling or rate limits, but such specifics are not essential for tool selection and invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances understanding by explaining that the default model is Workers AI Llama-3.3-70b (free) and that `_apiKey` is required to probe Anthropic, clarifying the relationship between `models` and `_apiKey`. It also mentions the per-model return object, which adds semantic value beyond the schema.

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

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

The description clearly states the tool's function: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It uses a specific verb (probe) and resource (LLMs), and distinguishes itself by focusing on visibility scoring across models. The output format is also mentioned, making it easy to understand the tool's unique value.

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 use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly name alternatives or state when not to use the tool, but the context is well-defined. It also explains how to request additional models, which is a practical usage guideline.

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

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

Annotations already declare readOnly/openWorld/idempotent, so the description adds meaningful behavioral context beyond them: the tool routes questions, auto-fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It also states that 'Ask_pipeworx itself selects and invokes the right underlying tool,' clarifying that this is a meta-tool or router rather than a direct data accessor. 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 overly verbose and repetitive: the 'prefer over web search' and 'use whenever' ideas appear multiple times, and the 'START HERE' guidance is redundant with earlier text. It also contains a garbled, unfinished segment ('A Window: ...') that appears to be a copy-paste artifact, undermining trust in the description's cleanliness. The content is front-loaded but not tightly edited.

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 the essential invocation contract: what to pass, what to expect back (structured answer with stable citation URIs), when to use it, and when to choose alternatives. It is sufficiently complete for an agent to select and call the tool correctly, though it doesn't discuss edge cases like extremely broad or ambiguous queries.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for 'question.' The description adds practical value by telling the agent that the tool 'fills arguments,' so the caller only needs to provide a natural-language question. The embedded examples ('What was Apple's revenue in 2024?') reinforce the expected input shape beyond the bare 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, high-value directive: 'PREFER OVER WEB SEARCH' and defines a distinct routing function — answering factual, data-oriented questions by invoking one of 5,767 tools and returning cited structured answers. It clearly distinguishes itself from web search and named sibling tools, making the tool's purpose unmistakable.

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

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

Use conditions are explicit and richly illustrated with trigger phrases ('what is', 'look up', 'get the latest'), domain categories (SEC filings, FDA data, economics, patents, etc.), and concrete examples. It even names sibling alternatives with their conditions: 'broad research overview, deep_research; for claims requiring verification, validate_claim; for comparing two entities, compare_entities; for monitoring ongoing changes, subscribe or recent_changes.'

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

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

The description discloses that behavior changes when a candidate routing improvement is under test and that no candidate is currently active, making it identical to ask_pipeworx. It also preempts a possible misconception by stating 'Falls back to nothing — this IS a full working router, just the experimental edge.' These details go well beyond the read-only/idempotent annotations and do not contradict them.

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

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

The description is four sentences and front-loads the beta identity before contextual details. Each sentence earns its place, covering current state, usage, and fallback clarification. It is slightly longer than strictly necessary but not redundant.

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

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

The description covers the tool's experimental status, current equivalence to ask_pipeworx, usage instruction, and fallback behavior, while also noting the same response shape. Annotations already cover safety and idempotence properties, so nothing critical is missing. An agent has enough context to invoke this beta router correctly.

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

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

The input schema provides 100% coverage, with all six parameters described as aliases for the required question parameter. The description adds 'same arguments' as a compatibility note, but no deeper semantic meaning for the parameters. Baseline 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 clearly identifies the tool as a beta version of ask_pipeworx, a universal router with 5,767 tools, and explicitly compares it to the stable sibling. It distinguishes itself by the experimental routing edge while noting it currently matches ask_pipeworx exactly. The purpose is unambiguous and the resource is named.

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 it exactly like ask_pipeworx when you want the newest routing. It also explains that results are compared against the stable router to inform merges, providing context for why this variant exists. This clearly guides an agent when to select it over the sibling tools.

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

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

Annotations already establish readOnly, idempotent, non-destructive behavior, so the bar is for added context. The description adds substantial behavioral detail: it routes across 5,767 tools, extracts only from tool results, returns a structured refusal when the source doesn't answer, and enumerates all refusal reasons. This goes well beyond the annotations.

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

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

Though dense, every sentence earns its place: purpose, routing behavior, return contract, refusal contract, usage guidance, and cost trade-off. The most important information is front-loaded, and nothing is redundant with 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?

This is a complex tool with no output schema, but the description fully compensates by specifying both success and refusal payloads, the grounding guarantee, and the cost/selection trade-off. An agent has everything needed to decide when to call it and what to expect back.

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 the schema already documenting that `question` accepts natural language and listing its aliases. The description adds little about parameters, but the schema carries the full burden, so the baseline score of 3 applies.

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

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

The description names a specific verb (answer) with a clear resource (Pipeworx sources) and sharply distinguishes this mode from ask_pipeworx via the grounded, hallucination-resistant extraction behavior. It tells the agent what the tool produces and why it exists.

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 this tool (answers that will be quoted, cited, or acted on, especially in high-stakes domains) and provides a direct alternative preference: use ask_pipeworx for casual lookups because this mode costs an extra LLM call. This is clear 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?

The description goes far beyond the annotations, detailing the resolver's confidence levels, fan-out behavior, short-circuit statuses for low-confidence or closed markets, tradeability warnings, and handling of rate limits (GDELT 429). It also discloses that medium/low matches may still surface fields and recommends inspecting the resolver contract before trusting analysis. This aligns with the openWorldHint and readOnlyHint, adding rich 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 long but well-structured with capitalized section headers, front-loading the purpose and usage. While every section adds valuable information, the overall length is extensive; it could potentially be trimmed without losing critical details, but the clear organization mitigates the verbosity.

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

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

Given the tool's complexity and the absence of an output schema, the description thoroughly explains the return structure (market, analysis, evidence, resolver contract, parent_event), safety behaviors, and edge cases. It even covers cancellation-rule risks and how to interpret low-confidence matches, making the description self-sufficient for an agent to invoke the tool correctly.

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

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

While the schema fully describes each parameter, the description adds substantial meaning: it specifies accepted formats for `market` (slug/URL/question text), the `depth` semantics (quick vs thorough with fan-out implications), and the `include_raw` trade-off (response size vs raw payloads). The classifier list and fan-out examples further clarify how inputs map to behavior, going well beyond the schema.

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

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

The description opens with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call', clearly stating the verb (Research), resource (Polymarket bet), and the mechanism (Pipeworx data). It also specifies accepted input formats and explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), which distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

The description provides explicit use-case triggers ('Use for...') and detailed fan-out examples for different bet categories, giving strong guidance on when to apply the tool. However, it does not explicitly name alternative tools or provide when-not-to-use exclusions, which would fully meet the 5-level criteria for usage guidelines.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context: it pulls latest 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years correctly, sorts results by primary metric, and returns citation URIs. This goes beyond what annotations provide, though it could mention rate limits or error handling.

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 moderately long but every sentence contributes useful information. It front-loads trigger phrases and the key 'ALWAYS PREFER' instruction, then logically details type-specific behavior, sorting, and output. No filler or redundancy; the structure is effective for a tool with two distinct entity types.

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

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

For a tool with two parameters and no output schema, the description covers the essential context: usage scenarios, data sources, metric sorting, and return format (paired data + citation URIs). It omits edge cases like pagination or error conditions, but given the tool's simplicity and rich annotations, the description is sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches parameter semantics by explaining what each type value means (company vs. drug) with specific data sources and metrics, and gives concrete examples for values (tickers/CIKs vs. drug names). This adds meaningful guidance beyond the schema's basic descriptions.

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

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

The description is exceptionally clear: it lists concrete trigger phrases, states the tool performs side-by-side comparison of 2–5 companies or drugs in a single parallel call, and differentiates itself from sequential single-pack lookups. It names specific data sources and output characteristics, leaving no ambiguity about its purpose.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and explains that it replaces 8–15 sequential lookups. It also implies when not to use it (for single entity lookups), providing clear situational guidance without naming sibling tools, which is sufficient.

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

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

Annotations already cover readOnly/openWorld/idempotent/non-destructive, so the bar is lower, but the description adds dense behavioral context: 15-60s latency (up to ~90s for thorough), parallel decomposition across 5,767 tools, the findings-packet shape (verbatim evidence, confidence, source, fetched_at, citation_uri), gaps[] never invented, contradictions[] on standard/thorough, semantic excerpting vs head-truncation, and the fetchability guarantee for citation_uri. 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?

Long, but well-structured and front-loaded: the most critical constraint (account required, with fallback) comes first, then purpose, then usage exclusions, then depth semantics, output guarantees, and latency. Every major section earns its place; minor redundancy like emphasizing 'ONE call' twice keeps it from a 5.

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 carry the burden of explaining return values, and it does thoroughly: findings-packet fields, gaps[], contradictions[], hop, citation_uri fetchability, and semantic excerpting. It also covers auth tiers, latency, edge cases (breaking news yielding empty gaps[]), and sibling routing — complete for a tool of this complexity.

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

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

Schema coverage is 100% for both question and depth, so the baseline is 3. The description still adds value: it explains what the depth values actually do behaviorally (standard's gap-recovery hop, thorough's lead-chasing iterative pass, contradictions[] only on standard/thorough) and clarifies that the question param is intended for broad/multi-part queries ('decomposition is the point'), pushing it slightly above the schema-only 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?

States a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources... in ONE call — this is NOT open-web search.' It clearly distinguishes itself from siblings by naming ask_pipeworx as the alternative for single lookups and live-news topics, so an agent can tell them apart without opening any schema.

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

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

Gives explicit when-to-use and when-not-to-use conditions with named alternatives: 'If you are not signed in, use ask_pipeworx instead,' 'Best for broad/multi-part questions over structured data,' 'For a single lookup use ask_pipeworx,' and for BREAKING/current-news topics 'prefer ask_pipeworx' with the concrete failure mode (mostly empty gaps[]) that justifies the exclusion. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the bar is lower. The description adds valuable behavior: returns top-N results with names, descriptions, full schemas, and curated examples, ready to call directly with no second lookup. It also clarifies that results are directly invocable.

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 ideal but front-loaded with purpose and usage. The domain list is arguably redundant with the schema examples but provides useful scope; each sentence contributes a distinct function (purpose, when-to-use, return format, first-step advice).

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 fully explains the return value: top-N tools with names, descriptions, and full input schemas, ready to call. Combined with annotations covering safety and idempotency, this is complete for a discovery 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%, with all six parameters documented including aliases and limit. The description adds marginal context ('describing the data or task' maps to query; 'top-N' maps to limit), but the schema already does the heavy lifting, so baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes this as a discovery/browsing meta-tool versus siblings like search_datasets or query_layer by listing the action verbs (browse, search, look up, discover) and the domain list.

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 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' This gives clear context, though it doesn't explicitly name alternative tools or a when-not-to-use beyond implying if you want one answer.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, and the description adds substantial behavioral context beyond that. It discloses the fan-out across multiple sources, soft-failure of the patents API, expected empty results for companies without FDA biologics, and the resolved:false private-company 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 long, but the tool is complex and has no output schema, so thoroughness is justified. It is front-loaded with use-case examples and organized by return fields, though some redundancy with the input schema could be trimmed.

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 behavior, and it does so comprehensively: it enumerates all returned sections, explains source success/failure reporting, highlights expected empty results, and covers resolution edge cases. An agent has enough information to know what the tool will return and how to interpret it.

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

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

Schema description coverage is 100% and the schema already fully explains type and value formats, including ticker, CIK, and name resolution. The description reinforces this with examples and notes that both type values behave identically, but it does not add significant new parameter 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 states a specific verb and resource: producing a full cross-source profile of a US public company in one call. It includes concrete user-prompt examples and explicitly contrasts itself with chaining single-pack SEC/XBRL/news lookups, making it easy for an agent to distinguish from other 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 says when to use this tool: user asks for a holistic view, 'tell me about X', 'research Acme', etc., and ALWAYS PREFER it over chaining single-pack lookups in those cases. It also explains behavior for edge cases like private companies and empty sections, giving clear guidance on expected outcomes.

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 safety profile is known. The description adds useful context about when deletion is appropriate, but does not go beyond annotations to explain side effects or error handling. It is consistent with annotations, so 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 concise sentences, front-loaded with the primary action, followed by usage contexts and sibling references. Every word earns its place; no redundancy or filler.

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

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

For a simple one-parameter destructive tool with strong annotations and full schema coverage, the description provides sufficient context for an agent to select and invoke it. It could mention what happens on success or when the key is missing, but this is not critical given its simplicity.

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% ('Memory key to delete' fully describes the only required parameter). The description adds no extra parameter-specific details, which is fine since the schema is complete. Baseline 3 is appropriate.

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

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

The description clearly states the action ('Delete a previously stored memory by key') with a specific verb and the exact resource. It differentiates from siblings by explicitly pairing with 'remember' and 'recall', making its role distinct.

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 contexts ('Use when context is stale, the task is done, or you want to clear sensitive data') and references related tools ('Pair with remember and recall'). It does not explicitly state when not to use it, 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds value by disclosing the internal behavior (fetches page, extracts title/description/key links) and the output format ('single text blob ready to drop at site-root/llms.txt'). This goes beyond annotations without contradicting them.

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

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

The description is three sentences, with each sentence serving a clear purpose: stating the core function, describing the process/output, and listing use cases. There is no wasted wording, and the structure is front-loaded with the most important information first.

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 moderate complexity (2 parameters, no output schema), the description is complete. It explains the purpose, the output format, and the intended use cases. Annotations cover safety, so no further behavioral information is needed. The description fully compensates for the lack of an output schema by stating the exact output type.

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 and max_links) already described in the schema. The description does not add any parameter-specific details beyond what the schema provides (e.g., it doesn't mention max_links). Since the schema carries the full burden, the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Generate'), a clear resource ('a production-ready llms.txt file for any URL'), and outlines the process ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format'). It clearly distinguishes itself from sibling tools by focusing on generating the llms.txt file itself.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor') which clearly indicate when to use the tool. However, it does not mention any exclusions or alternative tools, so it stops short of the full 'when/when-not/alternatives' guidance.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds valuable context about what 'schema' means here, listing fields, geometry type, record count, and capabilities, which goes beyond the minimal annotation information.

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

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

The description is a single sentence, front-loaded with the verb 'Get', and contains zero filler. Every word contributes to clarity and the output contents are compactly listed.

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

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

For a tool with one parameter and no output schema, the description fully specifies the expected return values (fields, geometry type, record count, capabilities). There are no missing behavioral or safety details that could prevent 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?

The schema provides 100% coverage of the single 'url' parameter, including type, description, and an example. The description only repeats that the operation is 'by url', adding no new semantic detail beyond what is already in the schema. Baseline 3 is appropriate because the schema handles the parameter documentation.

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

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

The description uses the specific verb 'Get' and clearly identifies the resource: 'an ArcGIS Feature/Map Service layer's schema by url'. It also enumerates the exact output contents (fields, geometry type, record count, capabilities), which distinguishes it from sibling tools like query_layer that retrieve actual data.

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

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

The description does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. The use case is implied by the purpose 'Get ... schema', but there is no direct guidance such as 'use query_layer for data queries'.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds useful context about caller-specific scoping and the exact return fields, which goes beyond the annotations.

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

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

The description is two sentences, front-loaded with the core action, and every sentence adds value. No unnecessary words 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 explicitly lists all return fields. Combined with rich annotations and a simple optional parameter, the description provides complete context for correct usage.

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

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

Schema coverage is 100%, and the one parameter (include_inactive) has a clear description. The tool description implies the default active-only behavior but doesn't add significant new 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 states 'List the caller's active subscriptions' with a specific verb and resource, and details the return fields. This distinguishes it from sibling tools like subscribe and unsubscribe.

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 says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear when-to-use context. It doesn't name alternative tools explicitly, but the guidance is 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?

The description goes well beyond the annotations (which are all false and uninformative). It discloses the claim_token workflow, rate limiting (5/day), quota exemption, daily digest behavior, and roadmap impact. It also clarifies the expected input style (describe in terms of Pipeworx tools, not user prompts). 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 longer than average but every sentence earns its place: purpose, usage, exclusions, token behavior, and operational details. It is front-loaded with the core purpose and then flows logically. Slightly dense as one block, but structured effectively.

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 feedback tool with no output schema, the description covers all essential aspects: purpose, when to use, what to include, token retrieval, rate limits, quota impact, and exclusions. The nested context object and enum are documented in the schema, and the description fills the remaining contextual gaps. It feels complete without being redundant.

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 meaningful context: it explains how to use claim_token (pass back later to read status), clarifies that message should be specific and not paste user prompts, and maps type values to feedback categories. This elevates it above baseline, though it doesn't elaborate on the structured context object beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately distinguishes this tool from research/query siblings by framing it as feedback, and enumerates concrete use cases (bug, feature/data_gap, praise). This clearly differentiates it from tools like ask_pipeworx or discover_tools.

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

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

Explicit when-to-use guidance is given: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a strong exclusion: 'if the tool came from a different MCP server ... file it with that server instead,' plus a disambiguation rule for identifying Pipeworx tools. This is model-tier usage guidance.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds meaningful behavioral context: it is "Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count)." It also discloses caching behavior: "Cached 5min-1h depending on window." This adds transparency about data provenance, privacy, and freshness, which goes beyond simple read-only intent.

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

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

The description is well-structured and front-loaded. The first two sentences establish purpose and output. The bullet-style list of use cases is efficient and scannable. The final sentence adds essential behavioral context (data source, privacy, caching) without fluff. Every sentence contributes necessary 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?

Despite having no output schema, the description tells the user what to expect: "top tools, top packs, and total call volume" and internally "just (pack, tool, count)." It also covers caching, data source, and non-PII. For a simple read-only tool with one optional parameter, this is complete enough to set accurate expectations. The absence of an output schema is compensated by the clear description of the return shape.

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

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

The schema already describes the window parameter fully with enum values and meaning: "24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand." The description merely restates the window options with no additional semantic detail. The schema covers 100% of parameter documentation, so 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 a clear, specific statement: "What other AI agents are calling on Pipeworx right now." It then details the return content: "top tools, top packs, and total call volume over a recent window." This clearly distinguishes it from siblings like ask_pipeworx (which likely answers questions) and discover_tools (which might list available tools), as it focuses on aggregated 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?

Provides explicit usage scenarios: "Useful for: (1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice before asking your own question, (3) seeing whether your use case aligns with what most agents need." This is concrete guidance on when to invoke the tool and what value to expect. Though it doesn't name alternatives, the context of siblings plus the clear use cases make usage guidelines strong.

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 (readOnly, idempotent), the description discloses rich behavioral details: the >3pp deviation threshold, the ≥0.30 Jaccard similarity filter, placeholder fraction >20% nulling, and the fill check that warns 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it'. It even explains output structure and edge cases, far exceeding the annotations' safety profile.

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?

Although dense, every sentence earns its place. The description is structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. The length is justified by the tool's complexity and the need to convey three modes, filters, and fill-check caveats without ambiguity.

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 zero output schema, the description compensates by describing response fields ('opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)') and the partition_check output. It also covers prerequisites, mode-specific behavior, filters, and trading caveats. This is fully complete for a complex tool with no 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%, but the description adds substantial meaning: it explains how the event parameter drives 'walks child markets, checks date-axis / threshold-axis ordering AND computes partition_check', and how topic 'searches related events across the platform, flattens markets, runs the comparator'. This transforms the parameters from simple strings into functional modes with concrete 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 opens with a specific verb-resource pair ('Find arbitrage opportunities on Polymarket') and explains the method ('monotonicity violations + partition-sum checks'). It clearly distinguishes this from sibling tools like polymarket_edges or polymarket_fill_risk by its dual-mechanism approach, and further details modes (event, topic, trending_scan). This is a textbook example of purpose clarity.

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

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

The description gives explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also names an alternative tool for custom sizing ('For custom sizing use polymarket_fill_risk'), providing a clear when-to-use vs alternative hierarchy.

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

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

Annotations already provide readOnlyHint and idempotentHint, but the description adds substantial behavioral context: it details the three model families, the edge_pp_net calculation, slippage handling, 24h-move warning, the exclusion of Fed candidates with rationale, response diagnostics, and 1h caching. This goes well beyond the annotations and provides valuable operational insight.

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 (~400 words) but densely structured with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, RESPONSE TOP-LEVEL). Every sentence contributes unique detail (model families, filters, response fields, caching). It is well-organized but arguably verbose; could be trimmed for clarity, so a 4.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is exhaustive: it specifies response structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields, segment gates, filtering knobs, and caching behavior. It even explains why segments may be empty and what diagnostics reveal. Without an output schema, this description carries the full burden and meets it.

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

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

The input schema already has 100% description coverage, but the description adds meaning beyond the schema: it explains tradeable-edge knobs (min_liquidity/max_spread_pp), clarifies that min_partition_leg_kelly applies to per-leg Kelly rather than parent-level, and discusses the design of slippage_pp (Polymarket has zero fees, etc.). This significantly enhances parameter understanding.

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

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

The first sentence clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This identifies the verb (scan/return), resource (Polymarket markets), and differentiates from siblings like polymarket_arbitrage or polymarket_edge_tracker by focusing on Pipeworx data disagreement.

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?

States 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' This clearly conveys when to use the tool (opportunity discovery) but does not explicitly name when not to use it or alternatives. The context is strong but lacks explicit exclusions, so a 4.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world. The description adds substantial behavioral detail: history depth is bounded by a 60-day TTL, snapshot gaps exist when no cache-miss occurred, decay is computed from daily closes net of default slippage, and the response format is fully described. This far exceeds what annotations alone 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?

Though lengthy, the description is perfectly structured with clear sections (purpose, args, response, limits). Every sentence adds unique information—no filler or redundancy. The response format is enumerated legibly, and limits are explicitly called out. The front-loaded first sentence immediately establishes the tool's purpose, making the length justified.

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 (time-series data, snapshot lifecycle, edge decay) and absence of an output schema, the description fully compensates. It explains the response structure (tracked[], expired[], snapshot_dates[]), the meaning of each field, the calculation methods, and the TTL/gap limitations. There are no obvious gaps in what an agent would need to know for correct invocation and interpretation.

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

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

The schema describes both parameters with 100% coverage, so the baseline is 3. The description adds meaning beyond the schema by introducing the concept of 'snapshot family' for the window parameter and explaining that days controls the lookback with default/max values (slightly different from schema's clamp range). It also clarifies how the parameters relate to the telemetry logic, adding value.

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

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

The description clearly identifies this as an edge persistence and decay telemetry tool, answering a specific question: "how long has this edge existed and is it shrinking?" It distinguishes itself from raw edge tools (like polymarket_edges) by focusing on historical snapshots and trend analysis, and explicitly contrasts a fresh wide edge with a 3-week-old one—making its unique value obvious.

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

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

The description provides clear context for when to use this tool: when edge age and decay matter. It implies it should be used over raw edge tools for understanding persistence, but it does not explicitly name alternatives or state 'use when X, not when Y'. The contrast between fresh and old edges effectively guides selection, but explicit exclusions are missing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false; the description does not contradict these and adds meaningful behavior: it 'walks the ladder', returns top_of_book/vwap/slippage/verdict, and highlights forced_directional_risk and thin_legs. It also clarifies size_usd semantics (max spend vs target proceeds vs settlement notional) and the dominant loss mode.

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

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

The description is a dense single paragraph without bullet points or section breaks, but it is front-loaded with the core purpose. Every sentence adds operational or risk information, though structural formatting would improve scanability. The length is justified by the tool's complexity (two modes, many return fields).

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 details return fields for each mode (e.g., top_of_book, vwap_fill_price, slippage_pp, verdict; and theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs). It also covers parameter validation ('REQUIRES one of') and use-case context, making it self-sufficient for an agent to select and invoke correctly.

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

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

Schema covers 100% of parameters with descriptions, but the description enriches them with mode-specific semantics: the difference between `market` and `event`, how `side` defaults differ by mode, and how `size_usd` is interpreted (spend, proceeds, settlement notional). It also notes default value and clamp range, adding value beyond the schema.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth' – a specific verb+resource+mechanism. It clearly distinguishes from siblings by naming polymarket_arbitrage and polymarket_edges as signals this tool should precede.

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 instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains the failure mode (partial basket fills convert arb into unhedged directional position). It also defines two modes (single-market and basket) with conditional parameters.

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

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

Annotations already declare readOnly/idempotent/non-destructive behavior, and the description goes far beyond them: it discloses pairing_unverified is set whenever pairs are returned, that unknown legs are never paired, that compatibility fields can be non-empty even with matched_pairs>0, and that spreads are gross of Kalshi fees. This is rich, honest behavioral disclosure.

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?

Long, but every sentence earns its place given the tool's complexity and the absence of an output schema. The description is front-loaded with purpose and mode selection, then organized into RESPONSE, SAFETY FIELDS, code list, and fee disclosure. Dense structure improves scannability rather than detracting from it.

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 carry the full burden of explaining return values, and it does: prices, top_spreads_pp, per-entry flags, temporal_alignment semantics including null handling, skipped counters, and fees_note. It even covers edge interpretation cases like temporal_alignment_unknown vs confirmed-aligned, leaving the agent with enough to call and interpret 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%, so baseline is 3, but the description adds real semantic value: it explains that each parameter overrides the topic-mapped side, that the two explicit parameters form a custom pairing, and that both modes run an identical token-overlap matcher. The topic enum list is repeated, but the override semantics and mode equivalence go 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?

Opens with a precise verb-plus-resource statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It immediately distinguishes itself from sibling tools focused on a single venue, and the two-mode structure further clarifies what it does.

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

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

The description gives strong contextual guidance: it names the two invocation modes ('topic' shortcuts vs explicit ticker/slug), explains that both run the same matcher, and warns that most pre-mapped topics currently return compatibility_warning. It doesn't explicitly name sibling alternatives to exclude, but the mode and caveat guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds behavioral context by stating it returns attribute rows and geometry, and mentions pagination via offset and limit. This goes 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?

The description is two sentences, front-loaded with the core action and parameter list. Every sentence adds value, and 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?

Given six parameters and no output schema, the description covers the tool's purpose, key parameter behaviors, return type (attribute rows and geometry), and a practical sampling pattern. It could mention error handling or response structure, but it is sufficient for an agent to select and 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 coverage is 100% with descriptions for all six parameters. The description adds little semantic value beyond the schema—it reiterates 'SQL-like where' and 'comma-separated out_fields' which are already in the schema. The sampling tip is useful but more about usage than 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 states the tool 'Query an ArcGIS Feature Service / Map Service layer by its url', providing a specific verb and resource. It distinguishes from sibling tools like search_datasets (which finds datasets) and layer_info (which likely describes metadata) by focusing on querying layer data.

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

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

The description provides workflow context by noting the URL comes from search_datasets, and includes explicit usage tips such as using where='1=1' with out_fields='*' to sample. While this gives clear context, it does not explicitly exclude when not to use the tool or name alternative tools for different scenarios.

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. The description adds valuable behavioral context beyond annotations: scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the conditional behavior of retrieving vs listing all keys. 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 four sentences long, front-loaded with the primary action, and every sentence earns its place: action, use case, scope, and pairing with sibling tools. No redundancy or filler.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It covers the tool's function, usage context, scoping, and relationship to related tools, leaving no significant gaps for an agent to select and invoke it correctly.

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

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

The schema description already covers the single parameter's semantics: 'Memory key to retrieve (omit to list all keys)'. The description reiterates this and provides illustrative examples of key values, but does not add new syntactic or format details beyond what the schema already specifies. With 100% schema coverage, a baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Retrieve') and clearly identifies the resource ('a value previously saved via remember') as well as the alternative mode ('list all saved keys'). It explicitly distinguishes itself from sibling tools by referencing remember (save) and forget (delete).

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 an explicit use case: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also explains when to use the key argument vs omit it, and names the paired tools (remember, forget), making the usage context fully clear.

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

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

The description discloses important behavioral traits beyond annotations: the persisted feed nature, the mark_read side effect (which modifies read state, explaining that the next call only shows newer ones), the return format, and polling suitability. This goes well beyond the readOnlyHint and idempotentHint annotations, providing actionable 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 the main action, and each subsequent sentence adds essential detail (return format, filters, mark_read behavior, polling, alternative endpoint). It is concise, with no redundant or filler information, and well-structured for an agent to parse.

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

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

Given five parameters, no output schema, and the presence of annotations, the description covers the behavior comprehensively: it explains what is returned, how filtering works, the mark_read side effect, and offers a URL for non-tool access. This is sufficient for an agent to understand the tool's full 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?

The schema already documents all five parameters with descriptions, achieving 100% coverage. The description mentions filtering by type and since, and setting mark_read, but these are restatements of schema properties rather than new semantic insights. It does not add detail like parameter formats or behavior beyond what the schema offers, 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 clearly states the verb 'Pull' and the resource 'fired events from your subscription feed', and further specifies return value elements (source, citation_uri, raw event payload). It is distinct from sibling tools like list_subscriptions and recent_changes, 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 gives clear context: it indicates that polling works fine and mentions an alternative access via GET registry.pipeworx.io/alerts.json for scripts/dashboards. However, it does not explicitly contrast with sibling tools or state exclusion criteria beyond the URL alternative, missing a direct 'when to use vs alternatives' statement.

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 and idempotent. The description adds behavioral details beyond annotations: fans out to multiple sources, GDELT preferred with GNews fallback on rate limits/5xx, USPTO soft-fail, and `since` date formats. No contradiction found.

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

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

Description is detailed but information-dense, covering query examples, source fan-out, parameter syntax, return shape, and sibling alternative. Slightly long but every sentence adds value for a multi-source tool.

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

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

No output schema exists, so the description must explain return values—and it does: structured changes[] grouped by source, total_changes count, and citation URIs. It also covers sources, fallback, time syntax, and sibling differentiation, making it fully self-contained for tool selection.

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

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

Schema covers all parameters with descriptions (100% coverage), but the description adds concrete examples for `since` (ISO date vs relative shorthand) and clarifies `value` accepts ticker or CIK. This enriches schema semantics beyond the structured definitions.

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

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

Description clearly states the tool provides a change feed for a company over a time window, with specific query examples. It explicitly distinguishes from entity_profile, making the purpose unambiguous and well-differentiated from 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?

Provides explicit usage scenarios ('What's new with X') and explicitly directs users to entity_profile for static profiles. It also explains fallback behavior (GDELT→GNews, USPTO soft-fail), adding practical guidance for when to use this tool.

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

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

Beyond annotations, the description discloses key-value scoping by identifier and persistence behavior (24 hours for anonymous sessions, persistent for authenticated users). This adds context not present in annotations.

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

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

The description is compact, with each sentence serving a purpose: definition, usage examples, storage mechanics, persistence details, and sibling pairing. No wasted words.

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

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

For a simple two-parameter tool with no output schema, the description covers what it does, when to use it, persistence semantics, and related tools, making it entirely actionable.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces key-value pairing but adds little beyond the schema's explicit 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 saves data for later reuse, using the specific verb 'Save' and resource 'data'. It also distinguishes sibling tools by explicitly pairing with 'recall' 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?

Provides explicit usage guidance: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference, research subject). It also mentions persistence differences and names recall/forget as alternatives.

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

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

Beyond the readOnly/idempotent annotations, the description discloses rich behavior: it cascades through multiple endpoints, degrades gracefully if GLEIF/OpenFIGI are unavailable, returns figi_candidates rather than guessing on ambiguous matches, labels identifiers by source, and explicitly lists unresolved identifiers. This gives the agent accurate expectations 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 front-loaded with trigger phrases and packed with useful detail, and every section earns its place. It is, however, one dense run-on block with somewhat repetitive example phrases, so it is not a model of concision.

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

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

With no output schema, the description explains the return behavior in enough detail: identifiers returned for company vs drug, the figi_candidates fallback, the unresolved field, and graceful degradation. Nothing an agent needs to select or call this tool correctly 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%, and the description adds substantial meaning beyond the schema: it explains input formats (ticker, CIK, ISIN, name), gives examples, and warns that for bonds only the issuer name should be passed and trailing security-class words will not match. This materially improves invocation correctness.

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 and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes itself from siblings by positioning itself as the first-step lookup tool ('Use FIRST whenever you have a name but need an ID') and gives concrete trigger phrases for ticker, CIK, LEI, RxCUI, and ownership questions.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID,' and scopes usage to company and drug types. It does not explicitly name sibling tools it should be preferred over or provide when-not-to-use conditions, though the intent is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the description needn't repeat safety. It adds useful behavioral context: internally probes each entity via ai_visibility_check, ranks results, and returns per-entity score/confidence/signal density. It does not mention rate limits or API key requirements, but those are in the schema.

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

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

Three sentences with no redundancy: first states core behavior, second gives a concrete example use case, third describes return value. Front-loaded and efficient.

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

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

No output schema, but the description specifies the return format (ranked list with score, confidence, signal density). It covers the workflow, use case, and internal mechanics. With strong annotations and full schema coverage, the description is complete for a tool of this complexity, though it could explicitly mention model/apiKey options.

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 four parameters are well-documented. The description adds minimal parameter nuance beyond the schema (e.g., first entity as subject is in schema). Baseline 3 is appropriate because the schema carries the load.

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 compares AI visibility across multiple entities, probes with ai_visibility_check, ranks by score, and highlights most/least recognized. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic) by focusing on competitive AI-marketing audits.

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

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

The description gives a clear use case (competitive AI-marketing audits) with an example question, and implicitly contrasts with ai_visibility_check for single-entity checks. However, it does not explicitly state when not to use this tool or name alternative tools for other scenarios.

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 behavioral traits beyond the annotations: it fans out across two services, partially fails gracefully, notes a 5-30s delay for bundlephobia's first measurement, and mentions the sources_failed field. This adds useful context not present in readOnlyHint/idempotentHint.

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

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

The description is dense but well-structured, with each sentence serving a distinct purpose: core function, usage guidance, return fields, ecosystem scope, and failure behavior. No redundant or filler content.

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

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

Despite lacking an output schema, the description enumerates all key return fields (is_latest, license, bundle_kb, etc.), explains partial failure behavior, and defines the ecosystem scope. This makes the tool's behavior self-contained and understandable for an agent.

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

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

Schema description coverage is 100%, so the parameters (package, version) are already well documented in the schema. The description adds no new parameter-level detail beyond what the schema provides, meriting the baseline score of 3.

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

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

The description clearly states the tool performs a composite check combining deps.dev and bundlephobia data for npm packages. It uses a specific verb 'check' and resource 'npm package', and its focus on dependency quality distinguishes it from sibling research 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?

Explicit usage guidance is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides a clear alternative for other ecosystems ('PyPI/Maven/Cargo/Go fall under deps.dev:version directly'), showing when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds value by specifying the exact return fields (name, summary, record_count, owner/org, Feature Service url) and the hand-off pattern, which is strong behavioral context.

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

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

Two sentences, no filler: the first states the primary purpose and scope, the second lists return contents and downstream usage. Every word earns its place.

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

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

The description is complete for this tool: it covers what it searches, what it returns, and what to do with the results. No output schema exists, so the explicit return-value listing is necessary and sufficient. Optional parameters are already fully documented in the 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?

The input schema has 100% description coverage for all three parameters with clear examples and descriptions. The description adds little parameter-specific detail beyond reinforcing that the query is keyword-based, so the baseline score of 3 applies.

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

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

The description uses a specific verb ('Search') and names the exact resource (Durham City-County GIS open geospatial datasets) with example topics. It also clearly differentiates from siblings by identifying query_layer / layer_info as downstream consumers of the returned Feature Service url.

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

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

The description clearly implies when to use this tool (find datasets by keyword) and explicitly directs users to query_layer / layer_info for subsequent operations. It lacks a formal 'when not to use' statement, but the alternative chaining is concrete and helpful.

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

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

Beyond the readOnly/idempotent annotations, the description reveals concrete algorithmic behavior: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and a 200K char cap with truncation and flagging. It also notes that each returned passage includes an offset for verbatim quote verification.

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

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

The description is front-loaded with the core action, then efficiently expands with examples, use-case, and technical details. Every sentence earns its place; there is no filler, redundancy, or irrelevant 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?

Despite lacking an output schema, the description specifies the return format: 'top-N passages with character offsets and similarity scores.' It also covers input limits, truncation behavior, and the intended pairing with another tool, making the description fully self-contained for an agent.

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

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

With 100% schema coverage, the baseline is a 3. The description enriches two parameters: it explains what kind of text to pass (e.g., SEC 10-K body, article) and provides concrete example queries. The 'limit' parameter receives no extra text, but its schema description is clear, so the incremental value is strong but not full.

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

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

The description opens with a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly differentiates the tool from siblings by explaining it works on text already pulled, and explicitly names ask_pipeworx_grounded with a distinct workflow.

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 condition: 'Use when the record is too big to cram into the prompt.' It also prescribes a workflow with ask_pipeworx_grounded, effectively contrasting with an alternative approach and giving the agent clear decision guidance.

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

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

Beyond annotations, the description discloses important operational behavior: auth requirements, type-specific filter syntax, delivery channel constraints (feed always on, sms requires verified phone with 10/day cap, webhook signing secret returned once and auto-disabled after 10 consecutive failures). This provides significant context that the annotations do not cover.

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

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

The description is dense but well-structured: it opens with a clear purpose, then requirements, supported types, and delivery details. Every section adds value without redundancy, and the length is justified by the tool's complexity.

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

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

It covers auth prerequisites, the main subscription types, delivery options with edge cases (phone verification, SMS cap, webhook disable), and return behavior (new subscription id and one-time webhook secret). Given no output schema and high tool complexity, this is thorough — even though two schema-defined types (patent_grant, clinical_trial) are omitted from the main description, the schema fills that gap.

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 detailed examples, giving a strong baseline. The description adds extra meaning such as 'items:["5.02"] = officer change' for sec_8k and webhook HMAC signing behavior, enriching the parameter semantics beyond the schema.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource, and notes it returns the new subscription id. This distinguishes it from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 clear context for proactive monitoring and mentions the OAuth prerequisite ('Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)'), implying use for ongoing alerts versus one-time queries. However, it does not explicitly exclude alternatives or name when not to use it, so it falls short of full explicit guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: results come 'from the live catalog of thousands of tools' and are organized by category, which goes beyond the structured annotations. 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?

A single dense paragraph that packs in examples, purpose, return format, and usage guidance. Every sentence contributes value, though the semicolon-heavy structure could be broken into shorter sentences for easier scanning. No 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 only one optional parameter and no output schema, the description fully covers what the tool does, what it returns, the categories offered, and when to use it. It even lists the category names and the meta-tools available, making it complete for onboarding.

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 only parameter `topic` with 100% coverage, including its enum values and behavior when omitted. The description merely echoes the topic examples ('finance', 'pharma', 'betting') without adding new semantic detail, so the baseline of 3 applies.

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

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

The description clearly states the tool is 'the onboarding entry point' that returns 'category-bucketed example questions' with the 'exact tool + argument shape' for each. It distinguishes itself from sibling tools like ask_pipeworx and entity_profile by positioning itself as the first step to learn what to ask.

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

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

Explicit 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 instructs when to call with no arguments vs. passing a topic, and references alternative tools (ask_pipeworx, entity_profile, compare_entities) for comparison.

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 this is a write operation (readOnlyHint=false), non-destructive (destructiveHint=false), and idempotent. The description adds valuable context beyond that: the row is deactivated (soft delete) not deleted, ownership is enforced, and historical events remain available. This is exactly the kind of behavioral nuance that helps an agent.

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

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

The description is two sentences, front-loaded with the primary action, and every sentence adds critical information. There is no waste or redundancy, 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 tool with one parameter, no output schema, and sufficient annotations, the description covers the key behavioral aspects (soft delete, ownership, retention of history) and cross-references recent_alerts. It doesn't mention error handling or edge cases (e.g., non-existent id), but given the simplicity, this is a minor gap.

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 fully describes the id parameter with 100% coverage, including that it's a subscription uuid returned by subscribe. The tool description merely restates 'by id' and adds no further semantic detail, so it provides no added value beyond the schema.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource ('subscription'). It distinguishes itself from siblings like subscribe and list_subscriptions by specifying cancellation. The mention of deactivation vs deletion further clarifies the tool's specific purpose.

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

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

The description provides clear context: ownership is enforced, so the tool is only for one's own subscriptions, and it references recent_alerts for historical events after cancellation. While it doesn't explicitly name alternatives, the constraints and cross-reference imply when to use this tool vs others.

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?

While annotations declare readOnly, openWorld, idempotent, and non-destructive, the description adds substantial behavioral context beyond these hints. It explains the two pipelines, the meaning of verdict types (especially distinguishing 'could_not_verify' as 'did not happen' with a verification_error and 'unsupported' as no source found), and notes the inclusion of verbatim evidence with pipeworx:// citations. This is far beyond annotation coverage and clarifies important failure semantics.

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. It front-loads with examples and usage, then details pipelines, verdicts, and error semantics. Each sentence adds functional value, though it could be slightly tightened without losing clarity. The structure flows well from purpose to behavior to return values.

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

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

With no output schema, the description fully compensates by enumerating the verdict types, explaining the actual value with citation, and specifying fields like verification_error. It also covers the two distinct execution paths and what 'unsupported' means. For a tool with this complexity, the description is remarkably complete, leaving little ambiguity about inputs, outputs, or failure modes.

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

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

The schema already describes both parameters with 100% coverage, but the description enriches them further. It explains that tolerance_pct overrides the tolerance implied by claim wording, gives a use case for hallucination detection, and specifies the default behavior (implied by wording, capped at 5). The claim parameter is exemplified with realistic phrases, which aids selection and formatting.

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

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

The description starts with natural-language examples and clearly states the tool's function: 'natural-language claim verification against authoritative sources.' It distinguishes the tool from siblings by explicitly describing the two execution paths (SEC EDGAR + XBRL fast path vs grounded pipeline) and stating it 'Replaces 4–6 sequential calls,' which differentiates it from generic query or research tools.

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

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

It gives an explicit trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies routing for company-financial vs other claims. However, it does not explicitly name alternative tools or provide 'when-not-to-use' exclusions, though the 'Replaces 4–6 sequential calls' hints at when this is preferable.

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