Arcgis Greenwood

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds meaningful context: the default model is Workers AI Llama-3.3-70b (free), and passing _apiKey means the user pays Anthropic directly. It also details the return structure (per-model {score, confidence, signals, raw_response} + combined view), which is not in 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?

Three sentences that each serve a clear purpose: define the action/output, explain default/cost behavior, and list use cases. The description is front-loaded with the core function and includes 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?

Despite lacking an output schema, the description explicitly enumerates the return fields (score, confidence, signals, raw_response) and combined view. It covers default model, optional Anthropic probing, and real-world use cases, making it complete for a read-only 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%, but the description adds that omitting models defaults to workers-ai for free, and clarifies that _apiKey is passed straight through to api.anthropic.com with cost implications. These details go beyond the schema's parameter descriptions, enriching the agent's understanding.

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

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

The description clearly states 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model,' providing a specific verb, resource, and measurable output. While it doesn't explicitly differentiate among siblings like scan_competitor_ai_presence, its unique model-scoring mechanism is evident.

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 sentence 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring' gives concrete scenarios for when to use this tool. It does not mention alternatives or exclusions, but the stated use cases are sufficient context for an agent.

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 all true, and destructiveHint false. The description adds valuable context by explaining the internal routing mechanism (picks the right tool among 5,563), return format (structured answer with stable pipeworx:// citation URIs), and that it covers many domains. 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 thorough but somewhat verbose, with multiple sentences reiterating the same domain list. While front-loaded with the key directive 'PREFER OVER WEB SEARCH', it could be more concise by grouping domains and reducing redundancy.

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

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

Given the tool's high complexity (5,563 tools, 1,462 sources), the description is comprehensive: it explains what the tool does, when to use it, how it works internally, what it returns, and how it relates to sibling tools. No output schema exists, but the description clarifies return format sufficiently.

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

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

Schema description coverage is 100%, so the schema fully documents the single required parameter and its aliases. The baseline is 3. The description adds value by providing multiple concrete usage examples and clarifying that the parameter accepts natural language questions. This lifts the score to 4.

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

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

The description clearly states the tool routes questions to one of 5,563 tools across 1,462 sources for authoritative structured data with citations. It distinguishes itself by covering a vast range of factual domains and is explicit about preferring this over web search.

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

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

Provides explicit guidance on when to use this tool (prefer over web search, start here for most questions) and when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers with verbatim evidence, deep_research for broad/multi-part questions). Also mentions breaking news handling.

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

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

The description adds value beyond the annotations by revealing the current state: 'No candidate is active right now... so this currently matches ask_pipeworx exactly.' It also clarifies that it is a full working router with no fallback behavior. The annotations (readOnlyHint, idempotentHint, etc.) are consistent and not contradicted.

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 efficiently structured: it opens with the core purpose, then explains the current state, usage guidance, and fallback behavior. Each sentence adds value without unnecessary repetition. It is slightly longer than minimal but still concise for the complexity of the tool.

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

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

Given the tool's complexity (beta router with experimental routing, 5,563 tools, no output schema), the description adequately covers the current state, the experimental nature, and how it relates to the stable version. It explains the fallback behavior and the fact that it's a full working router. The lack of output schema is compensated by referencing the same response shape as ask_pipeworx.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'same arguments, same response shape' but does not add any new meaning or usage guidance beyond what the schema already provides for the question parameter and its aliases.

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

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

The description clearly states it is a beta version of ask_pipeworx, a universal router with 5,563 tools, and explicitly distinguishes from sibling tools like ask_pipeworx (stable) and ask_pipeworx_grounded. It specifies the verb 'ask' and resource 'pipeworx' with the experimental routing context.

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

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

The description says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It provides clear context for when to use it, but does not explicitly state when not to use it or mention alternatives beyond the stable version.

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?

Description adds significant context beyond the annotations: it explains the hallucination-resistant extraction process, the explicit refusal reasons, and the cost trade-off. The annotations (readOnlyHint, idempotentHint, etc.) are consistent with this 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 well-structured and front-loaded with the core purpose, followed by process, return format, usage guidance, and cost. While slightly long, each sentence contributes unique value. Minor improvements could trim redundant phrases.

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 (high-stakes, hallucination-resistant, multiple refusal reasons, cost trade-off), the description covers all necessary context: behavior, return structure, refusal handling, and when to use/avoid. No output schema exists, but the description details the return format sufficiently.

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

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

Schema description coverage is 100% with all parameters documented as aliases for 'question'. The description mentions the question is in natural language, which is already in the schema. No additional parameter semantics beyond what the schema provides.

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

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

The description uses a specific verb+resource ('Hallucination-resistant answer mode') and clearly distinguishes from the sibling `ask_pipeworx` by emphasizing extraction from tool results only. The return format and refusal reasons are explicitly listed.

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

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

Explicitly states when to use (high-stakes reads, financial/legal/medical queries) and when to prefer the alternative `ask_pipeworx` (casual lookups due to extra cost). This provides clear context for tool selection.

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

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

The description discloses rich behavioral details well beyond the annotations: resolver confidence levels, statuses like 'low_confidence_match' and 'market_closed_or_inactive', illiquidity warnings, cancellation-rule parsing, parent-event extraction, and news fallback behavior. These are substantive additions that help the agent understand edge cases and response semantics. No contradiction with the read-only, open-world, idempotent hints.

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

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

The description is front-loaded with a clear opening sentence, and it uses section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) to organize a large amount of necessary detail. However, it is extremely long and includes highly specific examples (e.g., ticker symbols, exact fallback mechanics) that could be trimmed or moved to supplementary material without losing core guidance.

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 high complexity and the absence of an output schema, the description goes to great lengths to explain return shapes, resolver confidence, parent-event extraction, news fields, safety statuses, and cancellation-rule risk. It leaves very little ambiguous for an agent trying to interpret the results and make safe decisions.

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 clear descriptions, but the tool description adds extra semantic depth by explaining how 'market' can be a slug, URL, or question text and clarifying the depth options ('quick = 2-3 evidence sources, thorough = full fan-out'). This goes slightly beyond the schema's baseline, justifying a 4 rather than a 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 opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes this from siblings by focusing on Polymarket bet research with fan-out and a market-vs-model comparison, and it lists explicit use cases like 'should I bet on X' and 'is there edge in Z'.

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

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

Explicitly states when to use the tool with the 'Use for' phrase and gives concrete example queries. However, it does not explicitly mention when not to use it or name specific sibling alternatives, so it lacks the 'when-not' exclusion dimension.

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

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description discloses how results are sorted (by primary metric), that paired data and pipeworx:// citation URIs are returned, and that off-calendar fiscal years are handled correctly. It also quantifies efficiency (replaces 8–15 lookups), adding behavioral context not captured by 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 each subsequent sentence adds unique value: data sources, fiscal-year handling, sorting, return format, and efficiency. No sentence is redundant; it is dense but well-organized.

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

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

There is no output schema, but the description explicitly states it returns paired data plus citation URIs per entity. It also explains sorting behavior and the metrics involved for each entity type, giving an agent enough context to invoke the tool and interpret the result without additional documentation.

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

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

Although the schema already has 100% coverage with descriptions for both parameters, the description enriches meaning by clarifying what each type pulls (e.g., company pulls latest 10-K revenue, net income, cash, long-term debt; drug pulls FAERS adverse-event counts, FDA approval counts, active trial counts). It also gives concrete examples for the values array, making the parameter semantics significantly clearer.

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

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

The description opens with concrete trigger phrases ("Compare X and Y", "X vs Y") and clearly states its function: side-by-side comparison of 2–5 companies or drugs in one parallel call. It differentiates itself from sequential single-pack lookups and specifies the data sources (SEC EDGAR/XBRL for companies, FAERS for drugs).

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," giving a direct instruction for when to use it. It also implies when not to use it (single entity lookups) and provides examples of queries that trigger it, effectively distinguishing it from siblings like entity_profile.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: account requirement, paid plan for 'thorough', parallel tool routing, findings packet with gaps and contradictions, hop field, citation_uri fetchability, semantic excerpting, and expected timing (15-60s, up to 90s). No contradictions with annotations. The description fully compensates for any missing annotation details.

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

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

The description is long but packed with essential information. It is front-loaded with the account requirement and alternative. Every sentence adds value, though some could be slightly more concise. Given the complexity of the tool, the length is justified. It is well-structured with clear sections.

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

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

The description covers purpose, usage guidelines, behavioral details, parameter semantics, output structure (findings packet with fields), limitations (gaps, breaking news), and timing. There is no output schema, but the description compensates by describing the return format. The tool's complexity is fully addressed, leaving no critical gaps for an agent to understand correct invocation.

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

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

Schema coverage is 100% (both parameters described in schema). The description adds value beyond the schema: depth enum values are explained in detail ('quick=3...', 'standard=5...', 'thorough=8... paid'), and the question parameter is described as 'Broad/multi-part is fine — decomposition is the point.' This helps the agent choose appropriate values. Score 4 because it adds meaningful context while the schema already provides structure.

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 does 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources... in ONE call'. It specifies the verb (research), the resource (structured data sources), and distinguishes from siblings like ask_pipeworx (single lookup, live news). The purpose is specific and unambiguous.

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

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

The description explicitly advises when to use this tool versus alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also mentions account requirement and suggests using ask_pipeworx if not signed in. Best-use cases are given: 'broad/multi-part questions over structured data'. This is exemplary 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 indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context: returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed'. 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?

Two well-structured sentences. The long enumeration of data categories in the first sentence is dense but informative, directly supporting the usage guidance. Each clause earns its place, maintaining conciseness without being terse.

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

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

Given the tool's purpose, the description adequately covers its scope, usage, and return value ('names, descriptions, and full input schemas'). No output schema exists, but the description explains what the results contain. The many sibling tools highlight the need for this discovery tool, and this description fully positions 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 coverage is 100% with all six parameters documented, including aliases. The description reinforces the natural-language nature of the query but does not add meaning beyond what the schema already provides. The baseline of 3 applies because the schema carries the semantic weight.

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

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

The description uses a specific verb ('Find') and resource ('tools') and clearly scopes the tool as a discovery mechanism for a wide range of data domains. It distinguishes itself from sibling tools that are specialized (e.g., deep_research, entity_profile) by explicitly positioning itself as the entry point for browsing available tools.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)'. This also implies a contrast with tools that give direct answers, providing clear guidance against using it for specific lookups.

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 failure modes and fallbacks: 'USPTO PatentsView API sunset May 2025 — soft-fails until reactivated' and 'GDELT→GNews fallback.' It also reveals the fan-out architecture across multiple sources and exact output fields.

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

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

The description is long but front-loaded with example queries and a clear purpose statement. Every sentence contributes either alternatives, constraints, or output details. It is denser than ideal, but the complexity of the tool justifies most of the length.

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

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

With no output schema, the description fully enumerates the return structure: cik, company_name, recent_filings with pipeworx URIs, fundamentals fields, patents, news, and LEI. It also covers input constraints and failure behavior, making the tool self-contained for the agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds concrete examples ('AAPL', '0000320193') and reiterates the critical constraint that names are not supported. It also ties the value parameter to output behavior, slightly enriching the schema.

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

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

The description opens with concrete example queries and a explicit verb phrase: 'full cross-source profile of a US public company in ONE parallel call.' This distinguishes it from sibling tools like compare_entities or deep_research by focusing narrowly on a single entity profile.

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

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

It explicitly states when to prefer this tool ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups') and gives a clear exclusion and alternative: 'names not supported (use resolve_entity first if you only have a name).' This is exemplary usage guidance.

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

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

Annotations already declare destructiveHint=true, and the description adds value by explaining why deletion is desirable ('clear sensitive data'). It does not contradict annotations, and the idempotentHint=true is consistent with a delete operation. However, it does not describe error behavior or return values, but given the simplicity and annotations, this is adequate.

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

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

The description is two to three short sentences, each serving a distinct purpose: the action, the usage context, and the pairing with related tools. There is no redundancy or fluff, making it highly concise and well-structured.

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 a single parameter, no output schema, and annotations covering safety, the description adequately explains the tool's function, usage, and related tools. It could be more complete by mentioning what happens if the key doesn't exist, but the idempotentHint=true annotation implies no error, so the level of detail is sufficient for this simple 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 description coverage is 100% (the 'key' parameter is described as 'Memory key to delete'). The tool description adds little beyond the schema, simply repeating 'by key.' No extra format or syntax details are provided, so the baseline of 3 is appropriate.

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

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

The description explicitly states 'Delete a previously stored memory by key,' using the specific verb 'delete' and identifying the resource ('memory') and the key parameter. It also distinguishes itself from sibling tools by saying 'Pair with remember and recall,' clearly positioning it as the counterpart to storage and retrieval 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 provides explicit usage contexts: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, offering clear guidance on when to use this tool versus related memory tools.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds behavioral details: it fetches the page, extracts title/description/key links, and emits a standard markdown format. This gives context about network activity and processing without contradicting the annotations.

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

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

The description is three sentences, each contributing value: purpose, process/output, and use cases. It is front-loaded with the main action and no unnecessary 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 2-param tool with no output schema, the description covers the complete context: what it does, how it works, what output to expect (a text blob), and when to use it. Annotations cover safety, making it self-sufficient.

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

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

Schema coverage is 100%, so the schema fully documents both parameters. The description does not add new parameter-specific semantics, but it does mention 'key links' which aligns with max_links. Baseline of 3 is appropriate.

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

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

The description clearly states the verb and resource: 'Generate a production-ready llms.txt file for any URL'. It also details the process (fetches, extracts, emits) and distinguishes itself from siblings by focusing on generating the file rather than just checking visibility.

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 use cases (client indexing, own project, competitor audit) that clarify when to use the tool. However, it does not explicitly contrast with sibling tools like ai_visibility_check or scan_competitor_ai_presence, so it lacks exclusions.

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

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

Annotations already declare the operation as read-only, idempotent, and non-destructive. The description adds concrete behavioral context by specifying the response contents: fields (name + type), geometry type, total record count, and capabilities. This goes beyond the annotations and tells the agent what to expect from the call, filling the gap left by the absence of an output 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?

The description is a single, front-loaded sentence that immediately states the action and resource, then lists the key outputs. Every word earns its place; there is no fluff or repetition.

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

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

For a tool with one parameter, rich annotations, and no output schema, the description is adequately complete. It enumerates the return values, compensating for the lack of a structured output schema. It does not address potential error conditions or variations between Feature and Map Service layers, but these are secondary for such a focused metadata operation.

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

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

The input schema covers the sole parameter `url` with a clear description and an example, achieving 100% schema coverage. The description adds no additional parameter-level detail beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Get') connected to a clear resource ('ArcGIS Feature/Map Service layer's schema') and enumerates the exact outputs (fields with types, geometry type, record count, capabilities). This clearly differentiates it from sibling tools like query_layer, which likely retrieves data rather than metadata.

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

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

The description implicitly defines when to use the tool: when you need schema/metadata for a layer. It does not explicitly mention alternatives or exclusions, but the purpose is clear enough to guide selection. No misleading statements; clear context without explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context about the caller scoping and the exact output fields, which enriches understanding beyond what annotations provide.

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

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

Two sentences with no fluff: the first states purpose and output fields, the second provides usage guidance. Every word earns its place.

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

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

For a simple list tool with one optional parameter and no output schema, the description is complete. It covers purpose, return fields, default behavior, and use cases, leaving no significant gaps.

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

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

Schema description coverage is 100% (the include_inactive parameter is well-described). The tool description only reiterates the default active-only behavior, adding minimal 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 enumerates the returned fields (id, type, params, created_at, last_fired_at, fire_count). 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?

The description says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing explicit use cases. While it doesn't name alternatives directly, it clearly implies a review role distinct from subscribe/unsubscribe.

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

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

Annotations are all false and provide no hints, so the description carries the full burden. It discloses rate limiting ('5 per identifier per day'), the claim_token follow-up flow, that filing is free and doesn't count against tool-call quota, and that the team reads digests daily. No annotation contradiction exists.

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 provides distinct, high-value information (use cases, exclusions, workflow, rate limits). It is front-loaded with the core purpose, then flows logically into usage constraints and operational details. Slightly verbose but not wasteful.

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

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

Given the tool's complexity (4 parameters, nested object, no output schema), the description is complete enough for an agent to invoke it correctly. It covers the full feedback lifecycle, constraints, follow-up procedure, and scope, leaving no critical gaps about when or how to use 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 coverage is 100%, so the baseline is 3. The description adds meaningful guidance beyond the schema: explaining how to use claim_token to follow up on a prior report, and instructing users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts. This enriches the semantics of the message and context parameters.

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 ('Tell the Pipeworx team') and clearly identifies the resource (feedback about Pipeworx tools). It explicitly enumerates use cases (bug, feature/data_gap, praise), which distinguishes it from sibling tools like ask_pipeworx or deep_research.

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

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

Provides explicit when-to-use guidance for each feedback type and an explicit when-not-to-use exclusion: feedback about other MCP servers should be filed elsewhere. It also names an alternative action ('file it with that server instead') and clarifies what Pipeworx tools are, leaving no ambiguity.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds valuable behavioral details: it's 'derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window.' This informs the agent about data provenance, privacy, and freshness, which 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 information-dense but well-organized: it leads with the core purpose, then details outputs, use cases, and caveats. Every sentence earns its place, though the 'Useful for' list adds length. It is not as minimal as a two-sentence description but remains 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?

With no output schema, the description compensates fully by explaining both the return content ('top tools, top packs, total call volume') and the data shape ('just (pack, tool, count)'). It also covers caching behavior, making it complete for an agent to invoke and interpret results correctly.

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

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

The schema already provides a full description for the 'window' parameter, including the default and the effect of shorter vs longer windows. The tool description merely mentions the same options ('24h, 7d, or 30d') without adding new meaning, so it adds no value beyond the schema's high 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's function: 'What other AI agents are calling on Pipeworx right now' and specifies the exact outputs ('top tools, top packs, and total call volume'). This specific verb+resource framing distinguishes it from sibling tools like discover_tools or ask_pipeworx, which serve different purposes.

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: 'Useful for: (1)... (2)... (3)...' giving clear context for when to invoke the tool. It does not name alternative tools or state explicitly when not to use it, but the scenarios are sufficiently clear to guide an agent.

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 substantial behavioral detail beyond the readOnlyHint annotation: the monotonicity/partition-check algorithms, Jaccard similarity threshold (≥0.30), placeholder filtering (>20% returns null), and the fill check with CLOB depth and realizable_edge_pp logic. It also explains the response structure, leaving little implicit about side effects or edge cases.

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

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

The description is long but tightly organized with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose and mode selection. Every sentence adds operational detail, and the structure aids comprehension rather than bloat.

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 compensates by explicitly listing response fields (opportunities[], gap_pp, suggested_trade, partition_check) and edge-case outputs (realizable_edge_pp ≤ 0 means do not trade). It also covers all call modes, filters, and fallback behavior, making it fully self-contained for a complex tool.

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

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

Although the schema already provides 100% parameter coverage, the description enriches both parameters with operational context: event explains slug format, URL acceptance, and child-market traversal; topic explains cross-event search, flattening, and union processing. This goes well beyond the schema's one-line descriptions.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket', then details three modes (no args, event, topic) with distinct behaviors. This clearly distinguishes it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Explicit guidance is provided for each call mode: 'Call with NO args for a trending_scan', 'pass `event` for the strongest per-event partition_check', and 'pass `topic` for a themed cross-event scan'. It also recommends event for specific markets and points to polymarket_fill_risk for custom sizing, giving clear when-to-use and alternative tool 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 (readOnlyHint, idempotentHint, destructiveHint=false) by disclosing caching behavior ("Cached 1h at the KV level keyed on all knobs"), response structure (by_segment, fed_candidates, _diagnostics), edge calculation specifics (slippage, Kelly caps, per-sport bias corrections), and failure diagnostics (filter_skips, category_counts). It also warns about the 24h-move edge decay. This is rich behavioral disclosure that helps the agent anticipate outcomes without contradicting annotations.

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

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

The description is exceptionally long, but it is well-structured and front-loaded with a clear purpose. Each section (model families, response structure, knobs, diagnostics, caching) contributes useful information. Some internal model details (e.g., "lognormal barrier from 90d FRED log-returns") could be trimmed without losing selection value, but the organized layout and dense information justify a slight deduction for length.

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

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

With no output schema, the description fully documents the response top-level and per-opportunity fields. It explains why segments may be empty via _diagnostics and covers all 9 parameters in context. The combination of schema, annotations, and description leaves virtually no gap for an agent deciding whether and how to invoke the tool.

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

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

Although schema coverage is 100%, the description adds crucial meaning beyond the schema. For example, it clarifies that min_partition_leg_kelly is the only way to filter partition arbs because parent-level kelly_fraction_half is always 0, and it explains how slippage_pp interacts with Polymarket's fee-free but illiquid market. The tradeable-edge knobs (min_liquidity/max_spread_pp) are contextualized as guarding against unrealizable edges, which is not fully captured in the parameter descriptions alone.

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

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

The description opens with a specific verb and resource: "Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price." It clearly distinguishes itself from siblings like polymarket_arbitrage or polymarket_edge_tracker by focusing on Pipeworx-vs-market disagreement and by stating its intended use case: "what should I bet on today." The detailed breakdown of model families and response segments further reinforces a unique purpose.

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

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

The description provides clear when-to-use context: "Built for 'what should I bet on today' — agents discover opportunities without paging hundreds of markets." It also includes a when-not-to-trust caveat for Fed bets: "1m-T vs EFFR signal is unreliable at meeting-month horizons without paid OIS/SOFR-futures data." However, it does not explicitly name alternative tools (e.g., polymarket_arbitrage) or state when to prefer them, keeping it just short of a perfect score.

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

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

Annotations already mark this as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavior: snapshots written only on cache-miss (gaps), 60-day TTL, decay computed on daily closes, and response includes snapshot_dates. This goes beyond the annotation baseline without contradicting it.

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

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

The description is long but efficiently structured with ARGS, RESPONSE, and LIMITS sections. It front-loads purpose and uses telegraphic labels. Every sentence adds necessary detail for a complex telemetry tool; no fluff.

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

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

No output schema exists, but the description fully explains the return shape (tracked[], expired[], snapshot_dates[]) including fields like edge_pp_net, first_seen, trend, decay_pp_per_day, lifespan_days, and caveats about snapshot gaps. Limitations (TTL, start time, net of slippage) are also covered, making it complete for 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 baseline is 3. The description restates days and window inline but adds only marginal context (e.g., 'max 30' vs schema 'clamp 2-30', and 'snapshot family' already in schema). No 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?

Description clearly states it provides 'edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers 'how long has this edge existed and is it shrinking?'. This is a specific verb-resource pair distinct 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?

Gives concrete usage context: comparing fresh vs. old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'). While it doesn't explicitly name alternative tools, the context strongly implies when this tool is needed. No exclusions are stated.

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 declare readOnly, idempotent, and non-destructive behavior. The description adds depth by walking the ladder, detailing return fields like slippage_pp and max_fillable_usd, and disclosing the risk of partial basket fills converting an arb into an unhedged directional position.

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 uppercase mode labels and semicolon-separated lists. It is front-loaded with the core purpose and each sentence carries necessary detail for a complex, dual-mode tool. Slightly dense but 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?

With no output schema, the description enumerates all return fields for both modes, including top_of_book, vwap_fill_price, shares_filled, capture_ratio, thin_legs, and forced_directional_risk. It also covers edge cases like clamps and defaults, making it fully complete for 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%, but the description adds crucial mode-dependent semantics: how market vs event selects mode, side defaults per mode, and how size_usd is interpreted differently for single-market versus basket (settlement notional). This goes well beyond the schema.

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

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

The description opens with a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings by naming polymarket_arbitrage and polymarket_edges as contexts where this tool should be used.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the two modes and when each applies, giving clear direction for tool selection.

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

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

The description extensively discloses behavioral traits beyond the annotations: it explains compatibility_warning conditions, temporal alignment impact, skipped_cross_type/subtype meaning, and warns that pre-mapped topics often produce warnings. This is rich contextual information that the readOnly/idempotent hints do not provide.

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

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

The description is lengthy but well-organized with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. Every sentence carries technical value, though it could be slightly more concise without losing important caveats.

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 response structure, safety fields, warning conditions, temporal alignment, and leg-pair comparison counters. With no output schema, it fully explains what the agent can expect in the response, including edge cases and interpretation guidance.

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 each parameter already has a description. The tool description adds a two-mode conceptual frame and explains override semantics, plus the practical caution that 'pre-mapped ≠ tradeable.' This adds meaningful context beyond the schema, though it partly repeats schema content.

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

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

The opening sentence clearly defines the tool as "Cross-venue spread between Kalshi and Polymarket for the same resolving question," specifying the resource and action. It further distinguishes itself by focusing on bet-shape equivalence and when spreads are real signals, which differentiates it from generic arbitrage 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 clearly states the two modes of use (topic shortcuts vs explicit tickers) and provides context on when spreads are meaningful via compatibility_warning and temporal_alignment. However, it does not explicitly name alternative tools (e.g., polymarket_arbitrage) for when not to use this tool, only giving internal caveats.

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

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

Annotations already cover read-only/idempotent traits, so the bar is lower. The description adds useful context beyond annotations by stating the return type (attribute rows and geometry) and providing a sampling pattern. It does not discuss pagination behavior, error cases, or performance implications, but this is not critical given the safety annotations.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence contributes useful information (what it does, key options, sampling tip). No wasted words or redundancy.

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

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

For a tool with 6 parameters, good annotations, and no output schema, the description is sufficiently complete. It covers purpose, input source, return format, and parameter usage. It doesn't explain pagination/offset mechanics in depth, but the schema covers those. It could mention error handling or limits, but these are absent from the schema and not critical for basic use.

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 summarizes the parameters (SQL-like where, comma-separated out_fields, etc.) but does not add significant new meaning beyond the schema's own descriptions. The only slight addition is 'from search_datasets' indicating the URL source, but the schema already specifies the URL format. Therefore, the description adds minimal value over 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 queries an ArcGIS Feature/Map Service layer by URL, which is a specific verb+resource. It distinguishes itself from siblings like search_datasets (which finds datasets) and layer_info (which likely describes layers) by focusing on data retrieval. The mention of returning attribute rows and geometry clarifies the output.

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

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

It provides clear context: use this when you have a layer URL from search_datasets and want to retrieve data. It gives a practical sampling tip (where=1=1, out_fields="*") which implies when to use it. However, it doesn't explicitly state when not to use it or compare with alternatives such as layer_info or search_within, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only behavior is covered. The description adds valuable context about scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)'), which is not in the annotations, and explains the omitted-key behavior for listing.

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, all informative and front-loaded. First sentence states the primary function, second provides a use case, third covers scoping and relationship to other tools. No filler or redundant information.

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

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

For a simple tool with one optional parameter and existing annotations, the description covers purpose, use case, scoping, and related operations. It explains both invocation modes (retrieve by key, list all keys), which is sufficient given the lack of an output schema.

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

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

Schema description coverage is 100% and the 'key' parameter is already described as 'Memory key to retrieve (omit to list all keys)'. The description reinforces this but does not add new meaning beyond the schema; it simply restates the optionality.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses specific verbs (retrieve/list) and identifies the resource (saved keys), and distinguishes from sibling tools like remember and forget.

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

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

Explicitly states when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives: 'Pair with remember to save, forget to delete,' giving clear usage context relative to sibling tools.

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

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

Beyond the readOnlyHint annotation, the description reveals that returned events carry source, citation_uri, and raw payload, and that mark_read:true mutates the feed's read state to affect subsequent calls. It also explicitly states 'Polls work fine', providing helpful side-effect assurance. 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?

Four sentences, each earning its place: core action, return fields, filtering and state behavior, and an alternative access URL. The description is front-loaded and efficiently packed without fluff.

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

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

Despite the lack of an output schema, the description summarizes the return payload (source, citation_uri, raw event payload) and covers key parameters and the mark_read side effect. It also mentions an external endpoint for programmatic access. Given the tool's simplicity and thorough schema annotations, this is complete enough for an agent to invoke correctly.

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

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

The schema already documents all five parameters with high coverage. The description adds value with a concrete type example ('sec_8k'), clarifies since as an ISO timestamp, and explains mark_read's effect on future calls. It doesn't elaborate on limit or unread_only, but those are already self-explanatory in the schema.

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

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

The description opens with 'Pull fired events from your subscription feed', a specific verb and resource. It clearly identifies the tool's function as retrieving recent alerts from a persisted feed, distinguishing it from siblings like recent_changes.

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: it can be polled, filtered by type and since, and mark_read alters future behavior. It even points to an alternative HTTP endpoint for scripts/dashboards. However, it doesn't explicitly contrast the tool with sibling tools like list_subscriptions, so it lacks explicit when-not guidance.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds substantial behavioral context: single parallel call fanning out to multiple sources, GDELT→GNews fallback when rate-limited, USPTO soft-fail due to PatentsView API sunset. It also discloses the return format (changes[], total_changes, citation URIs). These details go far beyond the annotations and help the agent understand side effects and failure modes.

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

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

The description is dense but well-organized, progressing from natural-language examples to core function, source details, parameter syntax, return format, and alternative tool. Every sentence contributes useful information, though it's a bit long and could be tightened without losing key points. Still, the front-loading and structure make it easy to scan.

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

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

Despite no output schema, the description fully explains what the tool returns (structured changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It covers all data sources, fallback behavior, parameter formats, and the key alternative (entity_profile). An agent has enough context to invoke the tool expected and interpret results.

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

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

Schema already covers 100% of parameters, so baseline is 3. The description adds value by giving concrete examples for `since` ('2026-04-01', '7d', '30d', '3m', '1y') and clarifying that `value` accepts a ticker or zero-padded CIK. It also explains the `type` enum is limited to 'company'. This enriches the schema without redundancy.

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

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

The description opens with concrete natural-language examples ('What's new with X') then states precisely: 'change feed for a company in the last N days/weeks/months'. It names the specific resources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly distinguishes itself from the sibling tool entity_profile. This is a specific verb+resource+scope that leaves no ambiguity.

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 (recent changes, news, filings, patents) and explicitly names an alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains fallback behavior (GDELT→GNews on rate-limit/5xx) and USPTO soft-fail, giving an agent a clear decision framework.

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 (idempotent, non-destructive, write), the description adds critical behavior: memory is scoped by identifier, authenticated users get persistence, anonymous sessions retain for 24 hours, and it works across conversations/sessions. No contradiction with annotations.

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

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

Three sentences, front-loaded with the core action, followed by usage guidance and storage details. Every sentence earns its place; 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?

For a simple 2-parameter tool with full schema descriptions and useful annotations, the description covers purpose, usage, persistence behavior, and related tools. Nothing important 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 both parameters (key, value) are already well-documented with examples. The description reiterates that it's a key-value pair but adds no new meaning beyond the schema. Baseline 3 applies.

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

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

The description states a specific action ('Save data the agent will need to reuse later') with a clear resource (key-value memory). It distinguishes itself from siblings by directly mentioning complementary tools: 'Pair with recall to retrieve later, forget to 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?

Explicitly states when to use: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject).' It also positions against alternatives by naming recall and forget, making the choice obvious.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds significant behavioral context: cascading through multiple lookups, graceful degradation (LEI/FIGI enrichment degrades gracefully), handling of unresolved identifiers, and labeling of sources. No contradictions.

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

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

The description is front-loaded with examples and a clear use case. It is verbose but well-structured, with each section (supported types, inputs, behaviors) adding value. Some redundancy exists (e.g., 'cross-source identity spine' repeated), but overall it's effective.

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

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

Given the tool's complexity (two entity types, multiple identifiers, no output schema), the description covers input formats, resolution behavior, graceful degradation, and return semantics (unresolved identifiers explicitly stated, sources labeled). It does not detail the exact output structure, but it provides enough for an agent to understand what to expect.

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

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

Schema coverage is 100% with descriptions for both parameters (type and value). The description adds value by specifying that for company, input can be ticker, CIK, ISIN, or company name, and for drug, brand or generic name. It also explains ISIN-to-LEI mapping, which is beyond the schema. This adds meaningful context.

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

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

The description clearly states the tool resolves a name to canonical identifiers, with specific examples like 'What's the ticker for…' and 'find the CIK for…'. It distinguishes itself from siblings like 'compare_entities' and 'entity_profile' by being the first lookup step for obtaining IDs.

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?

Directly instructs 'Use FIRST whenever you have a name but need an ID.' and provides extensive context on when to use the tool, including supported types and input formats. While it doesn't explicitly say when not to use, the guidance is strong enough for an agent to decide.

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, and non-destructive hints. The description adds valuable operational context: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. 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?

Four concise sentences, each serving a purpose: the core comparison, the probing/ranking behavior, a use-case example, and return format. Front-loaded with the main action, zero 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 tool with no output schema, the description helpfully lists what the ranked list contains (score, confidence, signal density). It explains the operational flow and gives a real-world use case. The main gap is not explicitly addressing model selection or _apiKey, but those are 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?

Schema description coverage is 100%, so the baseline is 3. The description's mention of 'your brand + N competitors' mirrors the schema's entity semantics without adding new parameter meaning. No extra detail on models, _apiKey, or context beyond what schema already provides.

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

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

The description clearly states a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes from siblings by naming the underlying ai_visibility_check and focusing on multi-entity comparison, while the example use case makes the purpose concrete.

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

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

It provides clear context for use ('competitive AI-marketing audits') and an illustrative query. It does not explicitly state when not to use it or mention alternatives like ai_visibility_check for single-entity checks, but the multi-entity focus implies the differentiation.

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

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

Annotations already declare read-only, non-destructive, and idempotent behavior, and the description adds valuable context beyond that: it is a composite operation fanning out to multiple services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and failures are surfaced via 'sources_failed.' This rich behavioral detail fully discloses what happens behind the scenes and potential timing issues, exceeding 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?

Three dense sentences, each earning its place: the first defines the composite purpose, the second gives explicit use cases, and the third details outputs, limitations, and failure behavior. No filler or repetition; it is front-loaded with the most essential information and structured for quick parsing.

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 enumerates the summary block fields, per-advisory details, links, and alternative versions. It covers the NPM-only scope, partial failure behavior, timing expectations, and how failures are reported. This is exceptionally complete for a compound tool with 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 description coverage is 100%, so the baseline is 3. The description itself adds minimal param-specific detail beyond the schema; it mentions 'npm package name' and defaulting to latest version, but these are already in the schema. The only modest addition is clarifying NPM-only scope, but this doesn't significantly elevate 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 opens with a specific, verb-driven purpose: 'Composite should I add this npm package to my project check in ONE call.' It clearly names the resources (deps.dev and bundlephobia) and distinguishes itself from generic research tools by stating 'NPM ecosystem only in v1' and directing other ecosystems to 'deps.dev:version directly.' This is a clear, specific, and well-scoped 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?

Explicit guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also states when not to use it: for non-NPM ecosystems. This clearly communicates the intended use case and the alternative path for other registries, making it easy for an agent to choose this tool appropriately.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context by listing the exact returned fields (name, summary, record_count, owner/org, url) and indicating how the output should be used (pass url to query_layer / layer_info). This goes beyond the annotation-only safety profile and helps the agent anticipate the tool's output.

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

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

The description is two sentences, front-loaded with the core purpose and followed by concise return details and downstream integration guidance. Every sentence contributes value, with 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 search tool with no output schema, the description sufficiently explains return values and how to proceed. It does not explicitly handle the no-query case (e.g., list all datasets) or sorting/pagination, but the schema and examples cover optional parameters. The integration hint with query_layer / layer_info makes it complete enough for most use cases.

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

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

Schema description coverage is 100%, so each parameter (query, limit, org_id) is already documented with clear descriptions. The tool description adds no additional parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool searches City of Greenwood GIS open geospatial datasets by keyword, with a specific verb ('search') and resource. It distinguishes itself from siblings by enumerating the returned fields and explicitly pointing to query_layer / layer_info as follow-up tools, making its role in the tool family clear.

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

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

The description provides clear usage context: use this to discover datasets, then pass the returned Feature Service url to query_layer / layer_info. It does not explicitly mention alternatives or when not to use the tool, but it communicates the primary workflow and implies the tool is the entry point for dataset discovery.

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?

Description discloses behavior beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging. Returns character offsets and similarity scores. This complements the read-only/idempotent annotations without contradiction.

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

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

Three sentences, front-loaded with core action, then use case, then technical specifics. Every sentence contributes: the first defines the operation, the second explains when and why, the third provides implementation details and limits. 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?

For a tool with 3 params, no output schema, and no nested objects, this description is remarkably complete. It covers input, output (passages with offsets and similarity), limitations (200K cap, truncation), and integration with sibling tools. Annotations provide safety profile, so nothing critical is missing.

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

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

Schema covers all parameters with descriptions (100% coverage), so baseline is 3. The description adds extra meaning by illustrating the text parameter ('text you already pulled') and giving concrete query examples ('supply-chain risk', 'fiscal year 2024 revenue'). It doesn't deepen the 'limit' parameter but overall adds measurable value.

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

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

The description clearly states the tool does semantic search inside a user-supplied text string (a fetched record). It uses a specific verb ('search'), names the resource (text inside a record), and distinguishes itself from siblings by emphasizing 'already pulled' content and pairing with ask_pipeworx_grounded.

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

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

Explicitly instructs when to use: 'Use when the record is too big to cram into the prompt.' It also mentions a complementary alternative (ask_pipeworx_grounded) and explains the benefit of saving context. This goes beyond implied usage by giving clear context and a workflow.

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 says 'Returns the new subscription id', which implies each invocation creates a new subscription and is non-idempotent. This directly contradicts the idempotentHint=true annotation. Although other behavioral details are rich (webhook secret one-time, auto-disable after failures), this contradiction is a serious transparency failure.

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?

Front-loaded with core purpose and requirement, then structured by subscription type and delivery channel. Every sentence adds necessary detail without redundancy; 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?

With no output schema, the description must explain return values and side effects. It covers subscription id, webhook secret, always-on feed retrieval, verification requirements, delivery caps, and auto-disable behavior. Comprehensive for the tool's complexity.

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

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

Schema covers all parameters, but the description adds concrete examples per type (items:['5.02'], topic:'fed', series_id:'UNRATE'), clarifies delivery constraints (phone verification, 10/day cap), and explains webhook signing secret is returned once. This significantly enriches 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 opens with 'Create a proactive monitoring subscription to a live-data event stream', using a specific verb and resource. It enumerates supported types and delivery channels, clearly distinguishing it from sibling tools like list_subscriptions 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?

Provides clear prerequisites (Pipeworx OAuth account), supported types with examples, and delivery constraints (verified phone, 10/day cap). It doesn't explicitly name alternatives like list_subscriptions or unsubscribe, but the context and 'Returns the new subscription id' imply creation.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, establishing a safe, non-mutating profile. The description adds valuable behavioral context: output is 'category-bucketed example questions' drawn from a 'live catalog of thousands of tools,' and that it can be called zero-arg or with a topic. 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 a single, dense paragraph but front-loads the most useful information (example queries) before explaining purpose and usage. All sentences contribute value, though it could be broken into shorter sentences for readability. It's appropriate for the tool's onboarding role.

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

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

The tool is simple (one optional parameter, no output schema), and the description fully covers its purpose, usage, parameter semantics, and output nature (category-bucketed examples with exact tool/argument shapes). There are no gaps in understanding how to invoke it or what to expect.

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

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

The schema already describes `topic` with 100% coverage, including allowed values. The description adds that topic is optional and 'focuses' the output, with concrete examples ('finance', 'pharma', 'betting'), reinforcing the schema semantics. This elevates it above the baseline 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 opens with concrete user questions and immediately identifies the tool as 'the onboarding entry point for an agent that just connected...' and states it 'Returns category-bucketed example questions... each with the exact tool + argument shape.' This clearly differentiates it from siblings like discover_tools and ask_pipeworx, and explicitly tells the agent to use it 'FIRST when you do not yet know what Pipeworx can do for you.'

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

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

It provides explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains parameter behavior ('Call with no arguments for the full spread, or pass `topic`'). However, it does not mention when not to use it or contrast with specific sibling tools like discover_tools, so it falls just short of the highest bar.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description adds valuable behavioral context: ownership enforcement, soft deactivation (not deletion), and the effect on historical events. This fully discloses the mutating but non-destructive nature of the operation.

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, each conveying essential information with no redundancy. It is front-loaded with the core action, followed by important behavioral details, and maintains high information density.

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 single-parameter tool with no output schema, the description covers purpose, ownership, and behavioral consequences. It does not specify the return value, but this is acceptable for such a tool given the annotations and clarity of the operation.

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

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

The input schema provides 100% coverage for the single 'id' parameter, including its type and origin ('returned by subscribe'). The description adds no additional parameter semantics beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id', which is a specific verb-resource pair. It also distinguishes this from siblings like subscribe, list_subscriptions, and recent_alerts by mentioning the deactivation behavior and ownership enforcement.

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, and the subscription is deactivated rather than deleted, meaning historical events remain available via recent_alerts. This indicates when to use this tool versus other actions, though it does not explicitly name alternative tools.

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

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

Beyond the annotations, the description discloses critical semantics: could_not_verify means the check did not happen (and includes verification_error{stage,detail}), unsupported means no source coverage, and both must not be misinterpreted as evidence. This safety-critical detail is absent from annotations and adds real value.

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

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

The description is lengthy but each sentence is information-dense and purposeful. It is front-loaded with the core purpose and usage, followed by routing and edge cases. Slightly verbose but appropriately sized for the tool's complexity.

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

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

Even without an output schema, the description explains return verdicts, evidence citation, reasoning, and distinguishes two failure modes. For a tool with this complexity, the description provides enough context for an agent to invoke it correctly and interpret results.

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

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

Both parameters are fully described in the schema, and the description enriches them further with examples, tolerance_pct override behavior, default handling, and relation to verdict classification. This exceeds the baseline expected from 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 natural-language claim verification against authoritative sources, with specific trigger phrases and a defined scope. It distinguishes itself from sibling research tools by positioning itself as a single-call replacement for a multi-step pipeline.

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 whenever the agent needs to check whether something a user said is factually correct') and describes the routing logic for company-financial vs other claims. Does not name alternative tools, but the context is strong enough to guide selection.

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