Arcgis Coquitlam

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive. The description adds valuable behavior beyond that: default model selection ('Workers AI Llama-3.3-70b'), cost implications ('you pay Anthropic directly'), and the return structure (per-model {score, confidence, signals, raw_response} + combined view).

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

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

Three sentences, front-loaded with the primary action, followed by key options (default model, _apiKey) and use cases. Every sentence adds value; no filler or redundancy with schema.

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

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

For a 4-param tool with no output schema, this description fully covers inputs (entity, models, key, context), selection behavior, cost/auth, return format, and typical use cases. An agent can invoke this tool correctly and set expectations for the response.

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 4 params with descriptions (100% coverage), so baseline is 3. The description adds meaning by clarifying defaults ('free'), optionality ('Omit for just workers-ai'), and gives concrete examples ('Pipeworx', 'Acme Corp pricing') that help an agent understand how to fill the entity and context params.

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 ('Probe') and resource ('one or more LLMs') and clearly states the outcome (score visibility 0-100 per model). The scope is concrete (business/brand/product/topic) and distinct from sibling tools like ask_pipeworx or compare_entities.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to pass _apiKey ('to also probe Anthropic'). It does not explicitly mention sibling alternatives or when-not-to-use, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds meaningful behavioral context beyond annotations: it routes internally, fills arguments automatically, returns structured answers with stable citation URIs, and claims 'one fast call' with tier-wide availability. This goes beyond what the annotations provide, though it could mention potential latency or failure modes without hurting.

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

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

The description is long but front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and organized logically: domain list, mechanism, triggers, examples, and alternatives. Every section serves a distinct purpose, though it could be trimmed slightly without losing value. Overall, it is structured and efficient for its breadth.

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 highly complex meta-tool that routes to thousands of sources, the description covers all required context: what it does, when to use, examples, output characteristics (structured answer with citations), and differentiation from sibling tools. It also addresses edge cases like breaking news and tier availability. No output schema exists, so the description's mention of return format fills that gap adequately.

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 has 100% coverage for all 6 parameters, each alias described as 'Alias for question' with the main question parameter fully described. The description's examples (e.g., 'What was Apple's revenue in 2024?') add practical illustration but not new semantic meaning beyond the schema. It does hint that the tool 'fills arguments' automatically, which is a mild addition, but not significant.

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: it routes questions to one of 5,564 tools across 1462 sources and returns structured answers with citations. It also explicitly differentiates itself from siblings like ask_pipeworx_grounded and deep_research, making its unique role unambiguous.

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

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

The description provides explicit usage guidance: 'Use whenever the user asks...' with concrete triggers and examples. It also tells when NOT to use it by directing users to alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.' This is strong when-to-use vs. when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to repeat those. It adds context that it's a full working router and falls back to nothing, which is helpful. Since annotations cover the safety profile, the description's additions are adequate but not extensive; it doesn't detail response format or potential instability beyond the beta label.

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

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

The description is a single well-structured paragraph, front-loaded with the key beta distinction and current status. Every sentence contributes to understanding the tool's role and operational state, with no wasted words. Could be slightly shorter but is efficient.

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

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

For a complex router with no output schema, the description explains the tool's behavior and relationship to the stable version well. It notes the beta nature, that no candidate is active, and that it's a full working router. However, it doesn't clarify what 'validates against stable router' implies for users or any risk associated with experimental routing, leaving some gaps.

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

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

Schema coverage is 100%, so all parameters are documented with descriptions. The description adds minimal 'identical universal router' but no additional detail on parameter usage or format. Baseline 3 is appropriate because the schema handles parameter documentation; no further enrichment provided.

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 this is a beta version of ask_pipeworx, a universal router to 5,564 tools, and distinguishes it from the stable version by highlighting experimental routing improvements. It also notes the current inactive state, making the purpose and current status 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?

It explains when to use it — when you want the newest routing and are okay with experimental behavior — and contrasts it with the stable ask_pipeworx. However, it does not explicitly name alternatives or say when NOT to use it, leaving some ambiguity for edge cases.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description goes further by detailing the grounded extraction behavior, explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and the return format including evidence as verbatim quote. It also discloses the extra LLM call cost, adding significant behavioral context beyond the annotations.

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

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

Four sentences, front-loaded with the core value proposition, followed by return structure, use cases, and cost tradeoff. Every sentence serves a distinct purpose (what/why/when/cost) with zero redundancy, making it highly efficient.

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

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

The tool has no output schema, so the description compensates by fully explaining the return values (answer, evidence, confidence, source, fetched_at, refusal_reason) and describing the internal routing and extraction behavior. It also covers potential failure modes and when to use the alternative, making the description self-sufficient for an agent to invoke correctly.

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

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

Schema description coverage is 100% and the schema explicitly documents 'question' with aliases. The description doesn't add parameter-level details beyond what the schema provides, but it does contextualize that the question drives routing and tool selection. This meets the baseline of 3 for well-covered schemas but doesn't exceed it.

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

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

The description clearly states the tool's purpose as a hallucination-resistant answer mode for high-stakes reads, with a specific verb ('answers') and resource (Pipeworx grounded). It explicitly distinguishes from the sibling tool 'ask_pipeworx' by explaining it uses the same routing but then extracts answers only from tool results, making the specialization unmistakable.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on... must not invent facts.' Also gives an alternative: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost. This clearly differentiates from siblings and states 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?

Despite annotations already declaring read-only/idempotent/destructive-safe, the description adds extensive behavioral detail: it explains the resolver contract, low-confidence short-circuit behavior, closed-market handling, wide-spread illiquidity flag, news fallback mechanics, and resolution-rule risk. This goes well beyond what annotations provide.

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

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

The description is long but uses clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) to organize dense information. The first sentence is front-loaded with the core purpose. While not concise, every section adds critical operational knowledge for a complex tool, earning a 4 rather than a 3.

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 thoroughly documenting return shapes (market, analysis, evidence), the resolver contract (match confidence, alternatives, suggestions), parent_event extraction, news fallback fields, and safety/edge-case behavior. This gives an agent a complete model of what the tool returns and when to trust it.

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

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

The schema covers 100% of parameters with detailed descriptions, including examples, defaults, and tradeoffs (e.g., include_raw keeps responses under 20KB). The description adds little parameter-specific meaning beyond the schema, though it reinforces that market can accept slug/URL/question text. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ('Research') and resource ('Polymarket bet'), and distinguishes from sibling tools by emphasizing the one-call fan-out to category-specific data packs. It also lists explicit use cases ('should I bet on X', etc.), making its scope unambiguous.

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

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

The description provides explicit usage scenarios ('Use for...') and even gives fan-out examples across categories, which implicitly guides when to use it. It does not explicitly mention when not to use it or name alternative sibling tools, so it falls short of a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description goes beyond these by detailing exactly what data is pulled for each type (company: 10-K revenue, net income, cash, long-term debt; drug: FAERS counts, FDA approvals, trial counts), how off-calendar fiscal years are handled, sorting by primary metric, and the return format including citation URIs. This significantly enriches the behavioral profile.

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

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

The description is information-dense and every sentence adds value, front-loading trigger phrases and core purpose before diving into type-specific details. It is longer than typical tool descriptions, but this is justified given the two entity types and the need to explain data sources and sorting behavior. Slightly less structured than an ideal concise version, 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?

With no output schema, the description fully explains return values ('Returns paired data + pipeworx:// citation URIs per entity') and sorting ('Results sorted by primary metric'). It also covers what data is included for each entity type, how fiscal year nuances are handled, and the efficiency gain over sequential lookups. For a tool of this complexity, the description is complete and leaves no critical gaps.

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

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

Schema coverage is 100% with both parameters described, providing a solid baseline. The description adds further meaning by explaining behavior per type ('type="company" pulls LATEST 10-K...', 'type="drug" pulls...') and how values are used (e.g., tickers/CIKs for companies, names for drugs), which helps the agent choose appropriate inputs beyond the bare schema.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call, with specific trigger phrases ('X vs Y', 'compare', 'rank these companies'). It distinguishes itself from sibling tools like entity_profile by explicitly focusing on multi-entity comparison and noting it replaces sequential lookups.

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

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

The description explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear context for when to use this tool. It also notes it replaces 8–15 sequential lookups, but does not name a specific alternative sibling tool (e.g., entity_profile) or state when not to use it, so it falls short of the top 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?

The description goes far beyond annotations by detailing account requirements, parallelism across 5,564 tools, return format (findings packet with evidence/confidence/source/fetched_at), gaps[] never invented, contradictions[], hop field, citation_uri fetchability, semantic excerpting, and timing. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent and reinforced.

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 information-dense, covering critical operational details in a logical order: account prerequisite, uniqueness, engine mechanics, return structure, usage contrasts, depth variants, citation guarantees, and timing. Every sentence adds value; front-loaded with the most important caveat (account required).

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

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

For a complex tool with no output schema, the description thoroughly explains inputs, outputs, exception behavior (gaps[], contradictions[]), performance expectations, and integration with other tools. It fully prepares an agent to invoke correctly and interpret results, leaving minimal ambiguity.

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

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

Schema coverage is 100%, with detailed descriptions of both 'question' and 'depth'. The description adds practical depth semantics (quick/standard/thorough hops, paid plan for thorough, gap recovery, contradictions) and clarifies that questions are multi-part natural language, enhancing beyond schema alone.

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

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

The description states a specific action: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' with decomposition into facets, clearly distinguishing it from sibling ask_pipeworx. It explicitly contrasts with single-lookup and open-web search, establishing 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?

Explicit usage guidance is provided: 'Best for broad/multi-part questions over structured data', with direct alternatives such as 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. Also notes account/plan requirements for different depths.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it returns the top-N tools, includes full input schemas with curated examples, and results are directly callable without a second lookup. This goes beyond what annotations provide, though it does not mention pagination or potential variability in result quality.

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 with a clear verb, followed by a list of domains and a second sentence about return value and usage. The domain list is long but informative and earns its place by helping the agent know what topics are covered. It is not overly verbose, though it could have been slightly tighter by moving the domain list to a separate section.

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

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

For a discovery tool with no output schema, the description fully explains what it returns (names, descriptions, full input schemas, curated examples) and how to use it (call first when many tools are available). It also clarifies that results are ready to call directly, removing ambiguity about follow-up steps. This is complete for the tool's purpose.

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

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

Schema description coverage is 100%, so the schema already documents all parameters including aliases and the limit parameter. The description adds the concept of 'top-N most relevant tools' which maps to the limit parameter, but does not add significant new meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource ('Find tools by describing the data or task'), then enumerates the domains it covers (SEC filings, FDA drugs, etc.). It clearly distinguishes itself from sibling tools by emphasizing it returns tool schemas/descriptions, making it a meta-tool for discovery rather than a domain-specific data lookup.

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

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

Provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. It also hints at when not to use it ('not just one answer') implying you'd use a specific tool if you already know which one you need, though no explicit sibling alternatives are named.

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 read-only, idempotent, open-world, and non-destructive, and the description builds on this with rich behavioral detail: it fans out across SEC EDGAR, XBRL, USPTO, news, and GLEIF; explains the software-fail for USPTO's PatentsView sunset; and describes the GDELT→GNews fallback. This goes far beyond the structured annotations and gives the agent accurate expectations about failure modes and data sources.

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

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

The description is somewhat long and one continuous sentence, but every element carries information: examples, source list, output fields, fallbacks, and parameter constraints. It is front-loaded with user-facing trigger phrases and the primary purpose, so an agent quickly gets the gist before reading implementation details. The density is high but justified; a slightly tighter list-style format would earn a 5.

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

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

There is no output schema, so the description carries the full burden of explaining what the agent will receive. It enumerates the returned fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news mentions, LEI), includes the API sunset/fail-soft behavior, and notes input constraints and the fallback path. For a profile tool with this scope, the description adequately covers both inputs and outputs in a way that lets an agent invoke and interpret results correctly.

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

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

Schema coverage is 100% (both type and value are documented), so the baseline is 3. The description adds valuable semantics beyond the schema by giving concrete examples ('AAPL', '0000320193'), clarifying the zero-padded CIK requirement, and reinforcing the 'names not supported' constraint with a pointer to resolve_entity. It does not fully explain output formatting, but the parameters themselves are well contextualized.

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 establishes this as a comprehensive company profiling tool with example queries ('Tell me about X', 'company profile for Microsoft') and explicitly states it produces a 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from sibling tools by pointing to resolve_entity for names and by being preferred over chaining single-purpose lookups, giving it clear identity and differentiation.

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

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

The description gives explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states when not to use this tool directly ('names not supported — use resolve_entity first if you only have a name'), covering both use and exclusion criteria. This is model guidance for a tool description.

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 readOnlyHint=false, and the description's 'Delete' action aligns with these. The description adds usage context but no additional behavioral traits beyond what annotations provide, so it meets the baseline with annotations present.

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 total, front-loaded with the core action, then concise usage guidance and sibling context. No fluff 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 simple single-parameter delete operation with annotations and no output schema, the description fully covers what the tool does, when to use it, and how it relates to remember and recall. 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 coverage is 100% with the parameter 'key' described as 'Memory key to delete'. The description says 'by key', which matches, but does not add extra semantic detail beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the action ('Delete a previously stored memory by key') with a specific verb and resource, and explicitly distinguishes itself from siblings by mentioning pairing with 'remember' and 'recall' as the deletion counterpart.

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 conditions for use ('when context is stale, the task is done, or you want to clear sensitive data') and references related tools, giving clear guidance on when to invoke this tool.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds value by explaining the operational behavior: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This goes beyond the annotations by describing what actions are performed and the nature of the output, so a 4 is appropriate.

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 primary purpose, then mechanics, then use cases. Every sentence contributes new, non-redundant information. No fluff or repetition.

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

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

Given there is no output schema and only two simple parameters, the description is complete: it explains what the tool does, how it works, what it returns ('single text blob ready to drop at site-root/llms.txt'), and when to use it. No critical information is missing for an AI agent to select and invoke it correctly.

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

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

Schema description coverage is 100%: both `url` and `max_links` have clear descriptions, including formatting examples and defaults. The tool description adds no extra parameter-level detail, so the baseline 3 is correct—the schema does the heavy lifting.

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

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

The description opens with a specific verb+resource: 'Generate a production-ready llms.txt file' and clearly distinguishes the tool by specifying the output format and target use case (AI crawlers). This differentiates it from siblings like scan_competitor_ai_presence, which focus on auditing rather than generating the file.

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 ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), providing clear context for when to use it. It does not mention when not to use it or name alternatives, but the use-case list is strong enough for a 4.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds value by specifying the returned data (fields, geometry type, record count, capabilities), which goes beyond the annotations and clarifies what the agent can expect from the call.

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, focused sentence that front-loads the primary action and then lists the specific output details. Every word contributes meaning, with 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 one-parameter tool with strong annotations and no output schema, the description sufficiently explains what the tool does and what information it returns. It covers the key aspects of the tool's behavior and output, making it complete in this context.

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

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

The input schema has 100% coverage with a clear description for the single 'url' parameter including an example. The tool description's mention of 'by url' adds nothing beyond the schema. Since the schema already does the heavy lifting, a baseline score of 3 is appropriate.

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

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

The description clearly states a specific verb ('Get') and resource ('ArcGIS Feature/Map Service layer's schema'), and enumerates the exact output contents: fields, geometry type, total record count, and capabilities. This distinguishes it from sibling tools like 'query_layer' and 'search_within' which imply data retrieval rather than schema inspection.

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

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

The description implies the tool is for retrieving schema information but does not explicitly mention when to use it instead of alternatives, nor any exclusions or prerequisites. There is no direct comparison with sibling tools, leaving the agent to infer usage from the tool name and description.

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 read-only, idempotent, non-destructive nature, so the bar is lower. The description adds valuable context about the return fields (id, type, params, created_at, last_fired_at, fire_count) and caller-scoping ('the caller's'), which is not fully captured by the annotations.

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

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

The description is two sentences: the first states the action and return fields, the second gives usage guidance. Every word is necessary and it is appropriately front-loaded with the core purpose.

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

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

This is a simple read-only tool with one optional parameter, and the description lists all return fields, making the output explicit even without an output schema. Combined with the annotations and well-defined parameter description, the information is complete for safe and correct 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?

The input schema already provides 100% coverage for the only parameter (include_inactive) with a clear description and default value. The tool description does not add any extra parameter semantics, but this is acceptable given the high schema coverage, warranting the baseline score of 3.

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

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

The description uses the specific verb 'List' with the resource 'subscriptions' and further scopes it to 'the caller's active subscriptions,' which is precise and unambiguous. It also distinguishes from sibling tools like subscribe/unsubscribe by stating its use for reviewing before adding or finding an id to cancel.

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: 'before adding more or to find an id to cancel,' which directly references the workflows involving sibling tools subscribe and unsubscribe. This provides clear contextual guidance and implicit alternatives without needing to name them.

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 provide no strong behavioral hints (all false). The description adds valuable operational details: 'Filing without an account returns a claim_token; pass it back later... to read whether it was fixed and what changed,' 'Rate-limited to 5 per identifier per day,' and 'Free; doesn't count against your tool-call quota.' These go well beyond the schema and annotations.

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

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

The description is longer than average but every sentence earns its place: purpose, usage, exclusions, param guidance, token behavior, and constraints. It is front-loaded with the core purpose and then expands with operational detail. Slightly verbose, but no filler—a 4 rather than a 5 due to 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?

Despite no output schema, the description explains what the tool returns (claim_token), how to use it later, rate limits, scope, and exclusions. The 4-parameter schema (with nested context and enum) is fully covered by schema descriptions, and the description adds the missing behavioral context. This is complete for a feedback tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful param guidance: it explains how to use claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), and instructs users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which clarifies the message and context parameters. This lifts it above baseline.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist'—a specific verb and resource. It then enumerates the feedback categories (bug, feature/data_gap, praise) and explicitly scopes the tool to 'tools served by this Pipeworx connection,' distinguishing it from siblings like ask_pipeworx and discover_tools.

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

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

The description provides explicit when-to-use conditions ('Use when a tool returns wrong/stale data...', 'when a tool you wish existed isn't in the catalog...', 'praise') and a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' It also advises not to paste the end-user's prompt and clarifies identifying Pipeworx tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds valuable context beyond annotations: the data source (CF analytics-engine), absence of PII, output composition (pack, tool, count), and caching freshness (5min-1h). This enhances transparency 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 moderately sized but well-structured: a clear opening statement, a bulleted list of use cases, and a brief technical note about caching and data source. Each sentence contributes meaningfully; there is no redundancy or filler.

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

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

For a simple single-parameter tool with no output schema, the description covers the key return items (top tools, packs, total call volume), the data source, and freshness window. It doesn't specify the exact response structure, but the provided context is sufficient for typical 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?

The schema has 100% coverage for the single 'window' parameter, including an enum and a descriptive comment explaining the trade-offs between short and long windows. The tool description repeats the same window options without adding new semantic details, so it does not elevate beyond the schema's existing explanation.

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

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

The description clearly identifies the tool's purpose: it returns current trending tools, packs, and call volume over a specified window. It uses an action-oriented verb ('Returns') and describes the resource ('what other AI agents are calling on Pipeworx right now'), which distinguishes it from sibling tools like discover_tools.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming canonical tools, and checking alignment with agent needs). While it doesn't name specific alternatives or exclusions, the 'Useful for' section offers clear context for when to invoke the tool.

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

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

While annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description goes far beyond that with concrete behavioral details: default trending_scan of top ~200 markets, Jaccard similarity threshold of 0.30, placeholder partition filter at 20%, deviation threshold of >3pp, and the fill check against live CLOB depth with realizable edge at 1000 shares/leg. These operational details give the agent accurate expectations about what the tool computes and how to interpret failures.

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 structured with clear labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK), and every sentence carries operational value. The first sentence states the core purpose, followed by mode-specific instructions, making it front-loaded and easy for an agent to parse despite its 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?

Despite lacking an output schema, the description explicitly enumerates the response structure: opportunities[] fields, partition_check fields, and fill_check outputs. It covers edge cases (skipped_low_similarity, placeholder filtering), failure conditions (realizable_edge_pp <= 0), and cross-tool handoff to polymarket_fill_risk, making it fully self-contained for an agent operating in a complex decision context.

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

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

Schema coverage is 100% and parameter descriptions already exist, but the tool description adds substantial meaning: 'event' is tied to named examples and explains the walk over child markets and partition_check, while 'topic' clarifies cross-event scanning and the monotonicity union behavior. It also documents the important no-args mode even though there are no required parameters, enriching the agent's understanding beyond the raw 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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly distinguishes the tool from siblings like polymarket_fill_risk and polymarket_edges, which concern execution risk and edge tracking rather than cross-market arbitrage discovery.

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 mode selection guidance: no args for trending_scan, 'event' for specific markets, and 'topic' for cross-event scanning. It also explicitly recommends polymarket_fill_risk for custom sizing and warns not to trade when realizable_edge_pp <= 0, providing clear boundaries for when this tool should and shouldn't be used.

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

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

Beyond the readOnly/idempotent annotations, the description discloses rich behavioral details: 1-hour caching keyed on knobs, a 24h-move warning when recent movement exceeds the edge, 'tradeable-edge knobs' and their effects, segment-specific gate relaxation (Run 8), exclusion of Fed bets due to unreliable signals, and a diagnostics structure explaining why segments may be empty. This gives agents exceptional insight into the tool's runtime 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 dense and lengthy, but every sentence carries valuable information and it front-loads the core purpose before detailing segments, response structure, and caching. It could be better structured with bullet points for readability, but the information density is appropriate for a tool with 9 parameters and three complex segments.

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 specifies the top-level response structure (by_segment, fed_candidates/fed_note, _diagnostics) and lists the per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.). It also covers edge cases like empty segments, Fed data unreliability, and knob interactions, making it complete for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% with descriptive parameter entries. The description adds extra meaning, especially for the tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly), explaining how they interact with strategy segments and clarifying that min_kelly does not filter partition arbs because parent-level kelly_fraction_half is intentionally zero. This goes beyond the schema's per-parameter definitions.

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

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

The description clearly specifies the tool's action ('Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price') and its intended use case ('what should I bet on today'). It also distinguishes itself from sibling tools by focusing on discovering edge opportunities, and details the three output segments, making the scope precise.

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 states the tool is 'built for what should I bet on today' and notes it avoids paging hundreds of markets, providing a clear context for when to use it. However, it does not explicitly name alternatives or provide exclusion criteria (e.g., when to use polymarket_arbitrage instead), so the agent must infer usage boundaries.

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

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive. The description adds critical behavioral nuance: snapshot gaps indicate days no scan occurred, history is bounded by a 60-day TTL, and decay is computed from daily closes rather than intraday. It also details response semantics (tracked vs. expired, median lifespan) that annotations cannot convey.

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

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

The description is long but every sentence earns its place: it covers purpose, args, response schema, and limitations in a structured way. It is front-loaded with the core question, then details. Slightly verbose but justified by the 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 fully documents the return structure (tracked[], expired[], snapshot_dates[]) and explains fields like trend, decay_pp_per_day, and lifespan. It also covers edge cases (snapshot gaps, TTL limits, net-of-slippage) making it complete for an agent to invoke.

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

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

Schema description coverage is 100% for both parameters, so the schema already documents days (lookback, default 14, clamp 2-30) and window (24hr|1wk|1mo). The description adds minimal extra meaning, mostly restating the same defaults and adding 'lookback' context. Baseline 3 is appropriate.

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

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

The description states a specific purpose: tracking edge persistence and decay from historical snapshots. It answers a concrete question ('how long has this edge existed and is it shrinking?') and clearly distinguishes itself from the sibling polymarket_edges by focusing on time-series behavior rather than current edges.

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

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

The description implies when to use this tool by explaining that a fresh edge and a weeks-old edge represent different trade contexts, and it references the source of snapshots (polymarket_edges). However, it does not explicitly name sibling tools or state direct when-to-use/when-not-to-use alternatives, so it is clear but lacks explicit 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 readOnlyHint=true and destructiveHint=false, and the description adds detailed behavioral context: it walks the ladder, returns verdicts (clean|degraded|cannot_fill), explains partial basket fill risk, and names 'forced_directional_risk' legs. This goes well beyond the annotation baseline.

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 every section adds necessary information, structured with clear mode markers and usage guidance. The use of ALL-CAPS for REQUIRES, SINGLE-MARKET, BASKET, and USE THIS aids skimming. Slightly verbose but appropriate for a complex two-mode 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?

With no output schema, the description enumerates all key return fields for both modes, including per-leg fill detail, thin_legs, max_clean_notional_usd, and forced_directional_risk. It also clarifies defaults and clamps for size_usd, making the tool self-contained.

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: size_usd is 'USD to spend (buys) or target proceeds (sells)' in single-market vs 'settlement notional — shares per leg' in basket mode. It also explains side defaults and the auto behavior for basket mode based on partition sum.

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 performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishing between single-market and basket modes. This specific verb+resource framing separates it from siblings like polymarket_arbitrage and polymarket_edges.

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 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', providing clear when-to-use context and rationale about thin books and partial fill risks.

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

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

The description discloses extensive behavioral details beyond the annotations: safety fields, compatibility_warning conditions, temporal alignment flags, skipped_cross_type/subtype counters, and the warning that pre-mapped ≠ tradeable. This fully informs the agent about the tool's behavior and limitations, with no contradiction to the readOnly and openWorld 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 long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds useful information, though some redundancy exists (e.g., repeated emphasis on non-equivalent bet shapes). 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?

Given the tool's complexity, no output schema, and rich annotations, the description is complete: it explains the response structure (leg-by-leg prices, top_spreads_pp), safety edge cases, and temporal alignment meaning. It leaves no critical gaps for an agent to invoke the tool correctly or interpret results.

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

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

The schema covers all three parameters with descriptions. The description adds semantic value by explaining the topic shortcut list, override behavior of explicit parameters, and how the parameters map to the two modes. This enriches understanding beyond the schema's basic field descriptions.

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

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

The description states a specific action: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes from siblings by focusing on comparing identical events across two prediction markets, with explicit modes and response details.

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

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

The description explains when to use the tool, including the two modes (topic shortcuts vs explicit tickers) and clarifies that real spreads are rare and most pre-mapped topics return compatibility warnings. It lacks an explicit contrast with sibling tools like polymarket_arbitrage, but provides strong contextual guidance on when the output is meaningful.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds return behavior ('Returns attribute rows (and geometry)') and parameter behavior (SQL-like where, comma-separated out_fields), plus a sampling tip. 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?

Two sentences, front-loaded with the core action, and includes all key aspects (parameters, return, usage tip) without 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 read-only query tool with 6 params and no output schema, the description covers the purpose, return type (rows and geometry), required context (URL from search_datasets), and provides a sampling idiom. This is sufficient for an agent to invoke it correctly.

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

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

Schema covers all 6 params with descriptions (100%), so baseline is 3. The description adds meaningful usage guidance: SQL-like where syntax, comma-separated out_fields, and the sampling pattern where="1=1" and out_fields="*", which clarifies default behavior and gives a practical example.

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 'Query an ArcGIS Feature Service / Map Service layer by its url' – a specific verb and resource. It distinguishes from siblings by tying to search_datasets and specifying ArcGIS layers, making it clear this queries data rather than metadata or other services.

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 instruction 'from search_datasets' tells when to use it – after obtaining a layer URL from that tool. The tip 'Use where="1=1" + out_fields="*" to sample' provides a concrete usage scenario. However, it does not explicitly name alternatives or when not to use it.

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

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

The annotations (readOnlyHint, idempotentHint, destructiveHint=false) already indicate this is a safe read operation. The description adds valuable behavioral context beyond annotations, such as scoping to the agent's identifier ('anonymous IP, BYO key hash, or account ID') and the ability to list all keys. No contradictions with annotations.

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

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

The description is three sentences, front-loaded with the core action, and every sentence provides distinct value: the function, usage context with examples, and scope/companion tools. No filler or redundancy.

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

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

Given the tool's simplicity (one optional parameter, no output schema) and the presence of informative annotations, the description fully covers what the tool does, when to use it, its scope, and its relationship to sibling tools. The agent has enough information to select and invoke it correctly.

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

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

Schema description coverage is 100% (the only parameter 'key' is described as 'Memory key to retrieve (omit to list all keys)'). The description essentially repeats this behavior and adds examples of key content, but does not introduce new parameter semantics beyond the schema, so it meets the baseline of 3.

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

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

The description clearly states the tool retrieves a previously saved value or lists all saved keys, using the specific verbs 'Retrieve' and 'list'. It also distinguishes itself from sibling tools by explicitly mentioning 'remember' for saving and 'forget' for deleting, making the resource and operation unambiguous.

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

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

The description gives clear usage context: 'Use to look up context the agent stored earlier' with examples like 'user's target ticker, an address, prior research notes'. It also explains the rationale ('without re-deriving it from scratch') and pairs with companion tools ('Pair with remember to save, forget to delete'), though it doesn't explicitly state when not to use it.

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

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

Annotation reads readOnlyHint=true, but the description says 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a state-changing side effect. This directly contradicts the readOnlyHint annotation. The extra context about payload format and polling is useful but cannot overcome the contradiction.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence contributes useful information: purpose, return payload fields, filtering, mark_read semantics, polling, and an alternative access method. No wasted words.

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

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

No output schema exists, but the description specifies that returned events carry source, citation_uri, and raw event payload, which is sufficient return information. It also covers filtering, mark_read, polling, and the external endpoint. It does not mention limit or unread_only explicitly, but those are documented in the schema. Overall, context is complete for a tool of this complexity.

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

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

Schema coverage is 100%, giving a baseline of 3. The description adds meaning beyond the schema: it explains the effect of mark_read (flags read, changes future results), provides an example type ('sec_8k'), and clarifies since as an ISO timestamp. This exceeds baseline.

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

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

The description opens with 'Pull fired events from your subscription feed,' which is a specific verb+resource combination. It clearly distinguishes this from sibling tools like list_subscriptions by focusing on events/alerts already fired, and mentions the persisted feed and evaluator-written alerts.

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

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

The description gives clear usage context: polling is fine, and the same feed is available at an HTTP endpoint for scripts/dashboards, which implies the tool is for interactive use. It also explains filtering by type and since, and the mark_read behavior. However, it does not explicitly name sibling-tool alternatives or when NOT to use this tool.

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

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

The description discloses substantial behavioral details beyond the annotations: it explains the fallback chain (GDELT→GNews on rate-limit/5xx), the PatentsView API sunset and soft-fail, the specific external sources aggregated, and the output structure (changes[] + total_changes + citation URIs). No contradiction with readOnly/openWorld/idempotent hints.

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

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

The description is information-dense without fluff. It opens with concrete query examples, then covers data sources, fallback behavior, parameter formats, output shape, and an alternative tool in a compact, well-structured paragraph. Every sentence earns its place.

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

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

Despite having no output schema, the description fully explains the return format and includes edge cases (such as API sunset fallback). It covers all aspects needed for correct tool selection and invocation, and clearly differentiates from sibling tools.

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

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

Schema description coverage is 100% — all three parameters are documented in the input schema. The tool description mostly repeats the `since` format and adds a note that the window applies across sources, but it does not add new parameter semantics beyond what the schema already provides. Baseline 3 per rubric.

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

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

The description clearly states the tool's purpose: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It uses a specific verb and resource, and explicitly distinguishes itself from sibling tool entity_profile by explaining when to use that instead.

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 when-to-use guidance via example queries like "What's new with X" and also gives a direct alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This clearly tells the agent when not to use this tool.

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

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

The description adds significant behavioral context beyond annotations: persistence depends on authentication (authenticated users get persistent memory, anonymous sessions retain for 24 hours), data is scoped by identifier, and it's stored as key-value pairs. This discloses auth requirements and retention policy, which annotations do not cover. No contradiction with the idempotentHint.

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

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

The description is compact: four sentences that front-load the core purpose, then give usage guidance, storage details, and partner tools. Each sentence adds distinct 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?

Given the simple tool (2 required params, no output schema, no nested objects), the description fully covers purpose, usage triggers, persistence behavior, and complementary tools. It is sufficiently complete for an agent to decide when and how to invoke it.

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

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

Schema description coverage is 100% with informative descriptions for both key and value. The description reinforces the key-value model and gives usage examples, but adds little beyond what the schema already provides. Baseline 3 is appropriate given the strong 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 'Save data the agent will need to reuse later' — a specific verb and resource that immediately conveys the write operation. It further distinguishes itself from siblings by explicitly mentioning 'across sessions' and pairing with recall (retrieve) and forget (delete), making the tool's role 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?

It provides concrete guidance on when to use: 'when you discover something worth carrying forward' with examples like resolved ticker or user preference. It also explicitly names complementary tools ('Pair with recall to retrieve later, forget to delete'), clarifying the workflow and alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true. The description adds rich behavioral context: the tool cascades through multiple lookup endpoints, degrades gracefully (if GLEIF or OpenFIGI are unavailable, EDGAR identifiers still return), and returns unresolved identifiers explicitly. No contradictions with annotations.

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

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

The description is longer than average but well-structured: it opens with concrete examples, then defines purpose, supported types, and detailed behavior. Every sentence adds value, though some detail (e.g., the full LEI/FIGI explanation) could be condensed. It is front-loaded with the core usage pattern.

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

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

Given the tool's complexity (multiple entity types, external sources, cascading logic) and the absence of an output schema, the description is thorough. It explains fallback behavior, identifier labeling, and unresolved identifiers. A sample output structure would improve completeness, but the description is sufficient 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% (both parameters fully described). The description adds significant meaning: for 'company', it explains the full set of returned identifiers (CIK, ticker, LEI, FIGI) and the resolution logic; for 'drug', it mentions RxCUI, ingredient, brand, and a citation link. It also provides input examples (ticker, CIK, ISIN, name).

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

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

The description starts with concrete example queries ("What's the ticker for…", "find the CIK for…") and explicitly states the core action: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes itself from siblings by positioning as 'Use FIRST whenever you have a name but need an ID.'

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It details supported types (company, drug) and what each resolves, including fallback behavior when external sources are unavailable. It also notes that the tool replaces 2-3 manual lookups, reinforcing when to select it.

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

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

The description explains that the tool probes each entity with 'ai_visibility_check', ranks results, and returns a ranked list with score, confidence, and signal density. This adds behavioral context beyond annotations (readOnly, openWorld, idempotent) without contradiction, though it could mention potential rate limits or multi-call behavior in more detail.

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

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

The description is compact, front-loaded with the primary action, and every sentence adds value. It avoids redundancy and fits the main purpose, usage, and output in two sentences without excessive detail.

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

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

Despite having no output schema, the description covers the return format (ranked list with score, confidence, signal density) and the core workflow. It does not elaborate on interpretation of scores or edge cases, but for a 4-parameter tool with clear annotations, it is sufficiently complete for selection and invocation.

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

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

The schema already provides detailed descriptions for all four parameters (entities, models, _apiKey, context), and the description does not meaningfully add beyond what the schema gives. It reiterates the concept of comparing entities but offers no additional semantic value beyond the 100% schema coverage.

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

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

The description clearly states the tool's function: comparing AI visibility across multiple entities side-by-side, ranking by score, and surfacing most/least recognized. It distinguishes itself from sibling 'ai_visibility_check' by focusing on multi-entity comparison and from 'compare_entities' by specifying AI visibility 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 provides a clear use case (competitive AI-marketing audits) and references the underlying 'ai_visibility_check' probe, implying this is for comparing multiple entities rather than a single check. It does not explicitly state exclusions or alternative tools, but the context is strong enough for an agent to infer appropriate usage.

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

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

Annotations already establish read-only/idempotent safety. The description adds meaningful behavioral context: partial failure scenarios, bundlephobia's 5-30s latency on first measurement, and the sources_failed field. No contradictions, though rate limits or auth requirements are not mentioned.

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 carries useful information, from the primary purpose to output fields, failure behavior, and ecosystem boundary. It is front-loaded and structured logically, with only minor redundancy in the ecosystem note.

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

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

For a complex composite tool with no output schema, the description is unusually complete: it lists exact output fields, describes per-advisory detail, links, alternative versions, partial failure behavior, and latency caveat. The agent can fully predict behavior and return shape without additional context.

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

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

Schema covers both parameters with full descriptions, so baseline is 3. The tool description does not add extra semantics beyond what the schema already provides (e.g., default version behavior is already in the schema). It does not compensate for any gaps because there are none.

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 ('scan') and resource ('npm package'), and clearly frames it as a composite check across deps.dev and bundlephobia. It distinguishes from sibling tools by explicitly stating the NPM-only scope and directing other ecosystems to deps.dev:version.

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

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

'Use whenever an agent asks...' provides concrete triggers, and the NPM-vs-other-ecosystem exclusion tells the agent when NOT to use this tool. The alternative (deps.dev:version) is explicitly named, giving clear guidance for fallback.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds valuable behavioral context by specifying the return payload (name, summary, record_count, owner/org, and Feature Service URL) and how to use that URL, which helps the agent understand what to expect and what to do next. No contradictions with annotations.

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

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

The description is extremely concise: two sentences that front-load the core purpose and then provide essential return-value information. Every sentence earns its place; there is no fluff, repetition, or unnecessary detail. The structure is well-organized for quick comprehension.

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 explicitly lists the return fields (name, summary, record_count, owner/org, URL) and instructs what to do with the URL, making the tool's complete behavior clear. Combined with rich annotations for safety and 100% schema coverage for parameters, the description is fully sufficient for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100% with all three parameters (limit, query, org_id) already documented in the input schema. The description adds no new parameter-specific details beyond the schema, though it does mention keyword-based searching which aligns with the query parameter. Given the high schema coverage, the description provides no additional value beyond the baseline.

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

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

The description uses a specific verb ('Search') and identifies the exact resource ('City of Coquitlam GIS open geospatial datasets'), with concrete examples like 'parcels, zoning, parks & city services'. It clearly distinguishes itself from sibling tools by explaining that the returned URL should be passed to query_layer / layer_info, establishing a distinct search-then-query workflow.

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

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

The description implies the correct usage context by stating 'Search City of Coquitlam GIS open geospatial datasets by keyword' and then directing the user to pass the Feature Service URL to query_layer / layer_info. This provides a clear workflow for finding datasets versus querying them, though it does not explicitly list alternative tools or exclusions. The guidance is effective but not exhaustive.

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 and idempotent annotations, the description discloses algorithm details (BGE-base-en embeddings, cosine, 500-char overlapping windows), the 200K character cap with truncation flagging, and that results include character offsets and similarity scores. This gives an agent a clear behavioral model without conflicting with any 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 serve a distinct purpose: core functionality, use case, complementary tool, and technical limitations. The technical details are compressed into a single clause, keeping the description dense but highly readable.

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 covers return values (passages, character offsets, similarity scores), the use case, the pairing with ask_pipeworx_grounded, and the truncation edge case. It is self-contained and sufficient for an agent to decide when 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context by specifying what kind of text to pass (e.g., SEC 10-K body, article, long tool result) and explaining the top-N output with offsets and scores, going slightly beyond the schema field descriptions.

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

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

The opening sentence 'Semantic search INSIDE a fetched record' uses a specific verb and resource, clearly distinguishing it from sibling search tools like search_datasets. It further reinforces its unique role by describing segmentation into passages and pairing with ask_pipeworx_grounded, making the tool's scope unmistakable.

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

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

The description explicitly states when to use: 'Use when the record is too big to cram into the prompt' and highlights the context-saving benefit. It also describes a complementary workflow with ask_pipeworx_grounded, though it does not explicitly enumerate cases where the tool should not be used.

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 states 'Returns the new subscription id,' implying each call creates a new subscription, but annotations declare idempotentHint=true, which contradicts the described non-idempotent behavior. Per rubric, any contradiction with annotations requires a score of 1, despite the otherwise rich behavioral 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 dense but well-organized, front-loading the purpose and then covering types, channels, and constraints. It could benefit from bullet points or separate sections for readability, but every sentence carries meaningful information with 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?

The description covers authentication, subscription types, delivery channels, limits, and security caveats. However, it only mentions three of the five supported types in the overview (omitting patent_grant and clinical_trial), and webhook is only present in the schema's nested object, not the main description. The schema fills gaps, but the overview is not fully complete for such a complex tool.

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

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

Schema coverage is 100%, but the description still adds substantial value: concrete examples per type (e.g., items:['5.02']), phone verification requirements, 10/day SMS cap, webhook signing secret, and auto-disable after 10 failures. This goes far beyond the schema's field-level 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 and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It lists supported subscription types and delivery channels, clearly distinguishing itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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 usage context: when you want to monitor live data, which types are supported, and important prerequisites (e.g., OAuth account required, anonymous/BYO cannot persist subscriptions). It does not explicitly mention alternatives or when not to use, but the context is strong.

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

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

Annotations already indicate readOnly, openWorld, and idempotent hints. The description adds valuable behavioral context: it draws from a 'live catalog of thousands of tools', returns 'category-bucketed example questions', and mentions the exact tool + argument shape as output. This goes beyond the structured annotations, though it doesn't discuss rate limits or failure behavior. 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 informative but verbose, opening with a long slash-separated list of example questions that is more conversational than necessary. It front-loads key intent but could be tightened. The structure is logical (intent, output, usage), but the length and redundancy with the schema prevent a higher score.

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 fully explains what the tool returns (category-bucketed example questions with tool + argument shapes), how to invoke it (no args vs. topic), and when to use it. It also lists the categories and mentions the living catalog, making the tool's behavior complete for an agent evaluating whether to call it.

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

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

Schema description covers 100% of the topic parameter with an explicit list of values and a note to omit for a cross-category spread. The description largely repeats this ('finance', 'pharma', 'betting') and adds 'full spread' language, providing little extra meaning. The baseline of 3 applies because the schema already carries the semantic load.

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

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

The description clearly states the tool's purpose as an onboarding entry point that suggests questions an agent can ask Pipeworx. It lists specific behaviors: returns category-bucketed example questions with exact tool and argument shapes. This distinguishes it from siblings like ask_pipeworx and discover_tools by positioning it as the 'first' stop for exploration.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This provides clear when-to-use context and points to alternatives (ask_pipeworx, entity_profile, compare_entities). It also explains how to call with or without the topic argument, covering both usage modes.

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 key behavioral details: the row is deactivated not deleted, and historical events remain available via recent_alerts. This explains the soft-delete side effect clearly.

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

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

The description is two sentences, front-loaded with the action, and each sentence adds necessary information: what it does and the behavioral consequence. No wasted words.

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

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

For a simple one-parameter mutation tool, the description covers the action, ownership constraint, and side-effect behavior. It also links to recent_alerts for follow-up actions. No output schema exists, but the description doesn't need to explain return values given the simplicity.

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

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

Schema coverage is 100% with a clear description for the id parameter. The tool description adds only 'by id' and ownership context, which are already implied by the schema and annotations. No additional syntax or format details are provided beyond the schema.

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

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

The description clearly states the action 'Cancel a subscription by id', which is specific and distinct from sibling tools like subscribe and list_subscriptions. It also clarifies the scope (only own subscriptions), making it unambiguous.

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

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

The description gives clear context about ownership enforcement, implying you can only cancel subscriptions you own. It doesn't explicitly mention alternatives, but the pointer to recent_alerts for historical events is a useful contextual clue.

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 read-only and idempotent annotations, the description discloses critical behavioral nuances: the meaning of `could_not_verify` as a failed check (not evidence) carrying `verification_error{stage,detail}`, and `unsupported` as no source coverage. It also explains the two pipeline routes and the output structure (verdict, actual value, citation, reasoning), which are essential for correct interpretation.

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

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

Although longer than a simple tool description, every sentence contributes meaningful information: trigger phrases, pipeline routing, verdict definitions, and caller warnings. It is front-loaded with examples and contains no redundancy, making it appropriately sized for a complex tool.

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

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

The description is comprehensive for a tool with no output schema: it explains return values, the meaning of each verdict, failure modes, and how it replaces larger workflows. It covers both financial and non-financial claims, and the annotations complement it with safety hints, making the overall contract complete.

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

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

The schema already covers both parameters with 100% description coverage, so the baseline is 3. The description adds extra value by specifying the default tolerance cap ('capped at 5') and advising to set `tolerance_pct` to 1–2 for hallucination detection, offering guidance beyond the schema's basic description.

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

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

The description clearly states the tool's function as 'natural-language claim verification against authoritative sources' and provides concrete trigger phrases like 'fact check' and 'verify the claim that.' It also lists the specific verdict types returned, distinguishing it from sibling tools by noting it replaces 4–6 sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear usage condition. It also explains the two execution paths (financial vs. general claims) and notes that it replaces a multi-step workflow, but it does not name specific alternative tools or provide exclusions.

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