Data Calgary

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

Annotations (readOnlyHint, idempotentHint, destructiveHint=false) already convey safety. The description adds valuable context: the default model is free, using Anthropic requires a BYO key and direct payment, and the return format includes per-model score/confidence/signals/raw_response plus a combined view. This goes beyond the annotations without contradicting them.

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

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

Three sentences, front-loaded with the core purpose, then default/cost, then returns and use cases. No redundant words, every sentence earns its place. Excellent structural efficiency.

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

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

For a tool with 4 parameters and no output schema, the description covers the return structure (per-model object + combined view), the main use cases, and key behavioral notes. It lacks only deeper edge-case information (error handling, rate limits), which are not critical given high annotations and schema coverage. Very solid overall.

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 baseline is 3. The description adds meaning by noting the default model (Workers AI Llama-3.3-70b free) and explaining the cost/ownership of using _apiKey ('BYO key — you pay Anthropic directly for those calls'). This is useful behavioral context that the schema does not provide, nudging the score to 4.

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

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

The description uses a specific verb+resource construction: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes it from siblings like ask_pipeworx (which asks questions) and scan_competitor_ai_presence (which may have a different focus). It also outlines the return structure and use cases.

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

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

Explicit use cases are given ('AI-marketing audits, pre-launch brand checks, competitive monitoring') which clarify when to use. The description also explains the default model and optional Anthropic key with cost implications. However, it does not explicitly name alternative tools or state when not to use this tool, 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 this as read-only, open-world, idempotent, and non-destructive. The description adds additional valuable behavioral context: it routes questions to 5,564 tools across 1,462 sources, fills argumentative arguments, returns stable pipeworx:// citation URIs, and works on every tier on a single 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 front-loaded with the most important instruction: 'PREFER OVER WEB SEARCH'. It includes useful examples, source categories, and sibling-tool comparisons, but it is longer than strictly necessary; that verbosity is justified by the routing guidance though.

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 user receives: a structured answer with stable citation URIs. It also covers domain areas, example questions, when to use alternatives, and even news/breaking-topic handling, making the tool contextually complete for an agent to invoke it confidently.

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 fully documents the parameter 'question' and all aliases (q, text, input, query, prompt), so the schema already covers parameter semantics. The description adds little parameter-specific detail beyond noting that the question is natural language and that the tool fills arguments automatically, which keeps this at the baseline for high schema coverage.

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

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

The description clearly identifies ask_pipeworx as a default factual question-answering tool that routes questions to the appropriate sub-tool and returns structured answers with citation URIs. It also distinguishes itself from web search and sibling tools such as ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit guidance on when to use this tool: prefer it over web search for factual, current, or historical data queries, and use it as the default entry point. It also explains when to step up to ask_pipeworx_grounded or deep_research, fulfilling the when-to-use and alternatives criteria.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds that it is a full working router (not a fallback) and that outcomes are compared against the stable router. It doesn't detail potential behavioral differences beyond routing, but given annotations cover safety, this is adequate.

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

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

The description is a single, well-structured paragraph that front-loads the beta status and then clarifies current equivalence and usage. It is informative without excess, though could be slightly tighter.

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

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

Given the tool's complexity as a universal router, the description adequately explains its purpose, current state, and relationship to the stable version. It covers why an agent might choose it (newest routing) and reassures it's fully functional. Output format is not described, but the schema and sibling tool might handle that.

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

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

Schema covers all parameters with descriptions for the primary 'question' and aliases. The description notes 'same arguments' as ask_pipeworx, but does not add deeper parameter semantics beyond what the schema provides. With 100% schema coverage, 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 this is a beta version of ask_pipeworx, a universal router identical to the stable version but with live candidate improvements. It distinguishes from ask_pipeworx by its beta nature and explicitly says it currently matches exactly, so the agent knows exactly what it does.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and contrasts with the stable router. However, it doesn't explicitly say when NOT to use it (e.g., 'if you need stability, use ask_pipeworx'), but the guidance is clear enough.

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 indicate readOnlyHint and idempotentHint, which are consistent with the description's read-only and deterministic nature. The description adds valuable behavioral context: the exact return structure, refusal reasons, and the cost implication, which annotations do not cover. No contradiction, so a high score is justified.

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

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

The description is a single, dense paragraph that packs essential info without fluff. It front-loads the main purpose and includes key behavior, use cases, and cost trade-off, all in about 150 words. Every sentence adds value.

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

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

Despite no output schema, the description thoroughly explains the return format (including success and refusal variants) and expected error handling. It covers cost, use cases, and comparison to sibling, making it complete for an agent to invoke effectively with high confidence.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by explaining that the question is natural language and that aliases are equivalent. It doesn't describe the parameter in detail beyond what the schema says, but given full coverage, baseline 3 is exceeded slightly by the explicit mention of the question as natural language.

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

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

The description clearly states it is a hallucination-resistant answer mode for high-stakes reads, naming the verb 'ask' and the resource (Pipeworx). It explicitly distinguishes itself from the sibling 'ask_pipeworx' by describing a stricter extraction process and refusal behavior.

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

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

It explicitly states when to use this mode ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), naming the alternative sibling tool and noting the cost of one extra LLM call.

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

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

The description goes far beyond the annotations by disclosing resolver contracts (market_match_confidence, alternatives, suggestions), safety short-circuit behavior on low-confidence matches, closed-market status handling, wide-spread illiquidity warnings, cancellation-rule parsing with ev_impact, and news fallback details (429s, retry_after_sec). This level of edge-case transparency is exceptional.

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 capital-letter section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Each section provides non-redundant information. It is dense and could be shortened, but the structure keeps it navigable and 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?

Given there is no output schema, the description must explain return values, and it does so comprehensively: result.market, result.analysis, result.evidence, market_match_confidence/score/alternatives, parent_event fields, news metadata, and blocking statuses. It also explains resolution-rule risk and safety paths, making the description fully sufficient for agent invocation.

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

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

Schema description coverage is 100%, so the structure already fully documents the three parameters. The description adds no unique parameter-level semantics beyond what is in the schema; it instead focuses on behavioral and output details. 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 statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings like polymarket_arbitrage or ask_pipeworx by describing the fan-out to category-specific data packs and the market-vs-model comparison output.

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

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

Explicit use cases are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains input formats (slug, URL, question text). However, it does not explicitly state when not to use this tool or name alternative sibling tools for specific scenarios, so this is not a full 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds that results include dataset names/descriptions/resource ids, which is useful return-value context but lacks deeper behavioral detail like pagination or auth nuances. 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?

One compact sentence captures purpose, resource, and return value without waste. It is front-loaded and every clause contributes meaning.

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

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

Given no output schema, the description does well to list return fields. It also connects to calgary_query. It lacks explicit mention of pagination or rate limits, but those are covered by schema parameter descriptions, so the description is largely complete.

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

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

Schema description coverage is 100%, so parameters are already self-explanatory. The description adds nothing about parameter syntax or formats beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Search') and names the exact resource ('Calgary open-data catalogue'). It also states the return payload (dataset names, descriptions, Socrata resource ids), which clearly distinguishes it from sibling tools like calgary_recent and calgary_query.

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 that returned resource ids are for use with calgary_query, providing clear 'next-step' guidance. It doesn't explicitly exclude other tools or mention calgary_recent, but the keyword-search workflow is well implied.

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, and idempotentHint, covering safety. The description adds context on the raw SoQL nature, the full range of clauses supported, and the resource id format, which helps the agent understand the tool's behavior beyond structured hints. It does not contradict annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and every sentence earns its place. It avoids unnecessary detail while giving essential usage pointers.

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

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

Given the tool has no output schema and 8 parameters, the description provides enough context to invoke it correctly: how to get resource ids, the full SoQL capabilities, and the resource id format. It relies on the schema for detailed parameter limits, which is acceptable. It could be more complete by mentioning pagination or error handling, but annotations and schema cover most operational aspects.

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

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

The input schema provides 100% coverage with each parameter containing a description, so the baseline is 3. The description adds a little value by listing the SoQL clauses and giving the exact resource id format, but this is largely redundant with the schema's per-parameter descriptions. No meaningful additional parameter semantics are introduced.

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 runs a raw SoQL query against any Calgary open-data resource using a Socrata id. It uses a specific verb ('run') and resource ('Calgary open-data resource'), and distinguishes itself from siblings like calgary_datasets and calgary_recent by focusing on direct data querying rather than listing or retrieving common datasets.

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

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

It explicitly tells the agent to use calgary_datasets to find a resource id or calgary_recent for common ones, which effectively defines when this tool should be used (when you have a specific resource id) versus when to use alternatives. This is direct and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds useful behavioral context beyond that: it specifies ordering ('Returns the latest rows (newest-first)'), that it works by friendly name ('no Socrata id needed'), and supports SoQL filtering via 'where'. This adds meaningful behavior without contradicting annotations.

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

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

The description is concise and front-loaded, using four short sentences that each earn their place: purpose, usage guidance, dataset names, and ordering/filtering. It could be slightly tightened, but there is no waste or redundancy, making it highly efficient for an agent.

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 read-only tool with four parameters, no output schema, and robust annotations, the description covers essential context: what it does, when to prefer it, supported datasets, ordering, filtering, and the alternative tool. It does not describe return value format, but in the absence of an output schema, the description is sufficient for an agent to select and invoke the tool correctly.

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

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

The input schema already provides 100% parameter coverage with descriptions for all four parameters (limit, where, _apiKey, dataset), including an enum for dataset. The description does not add substantial parameter semantics beyond the schema, like clarifying the SoQL syntax or default limit, which are already in schema. Therefore, the baseline of 3 is appropriate.

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

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

The description clearly states the tool returns 'Recent records from a common Calgary open dataset by friendly name' with a specific verb ('Returns'), a resource ('Calgary open dataset'), and scope ('latest rows, newest-first'). It also distinguishes from siblings by explicitly naming the alternative tool 'calgary_query' for anything else, and lists the supported dataset names ('311, permits').

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

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

Explicit guidance is provided on when to use this tool: 'PREFER OVER WEB SEARCH for "Calgary 311 requests", "Calgary building permits"' and 'for anything else use calgary_query'. This clearly delineates use cases and alternatives, leaving no ambiguity about when this tool is appropriate.

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

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

The annotations already indicate safe read-only, idempotent behavior, but the description adds substantial context: SEC EDGAR/XBRL data sources, handling of off-calendar fiscal years (AAPL, NVDA examples), FAERS/drug-specific metrics, result sorting by primary metric, and return of paired data with citation URIs. 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 dense but every sentence earns its place: trigger patterns, preference guidance, type-specific data sources, fiscal-year handling, sorting, output format, and efficiency value. It is front-loaded with user phrasing and ends with the benefit, 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?

Given no output schema, the description covers the key return behavior (paired data, citation URIs, sorting by metric). It also covers scope limits (2–5) and data provenance. This is 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 coverage is 100%, but the description enriches both parameters: it explains what 'company' vs 'drug' types fetch (net income, trial counts, etc.) and gives concrete value examples like tickers and drug names. This goes well beyond the schema's basic enum and array 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 starts with explicit trigger phrases and clearly states the resource ('companies or drugs') and action ('side-by-side comparison of 2–5'). It distinguishes itself from sequential single-pack lookups, which is echoed by the sibling entity_profile, and explains the data sources and output.

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

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

The description provides explicit when-to-use signals ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and examples of user intent. It implicitly excludes non-comparison use cases and names the alternative (single lookups) it replaces, meeting the when/when-not/alternatives bar.

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

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

Despite strong annotations (readOnly, idempotent, openWorld), the description adds extensive behavioral context: decomposition into facets, parallel routing, gaps[] never invented, contradictions[], resolvable citation_uri, semantic excerpting, and expected timing. It also explains behavior for out-of-catalog topics (returns empty gaps). 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 dense and information-rich, with every sentence adding useful detail, but it is a single long paragraph. The tool's purpose is not front-loaded (the opening focuses on account requirements), and some details overlap with the schema. Still, given the complexity, the length is justified and there is no fluff.

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

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

The description is remarkably complete for a tool with no output schema. It details the return packet (verbatim evidence, confidence, source, fetched_at, stable citation), the gaps[] and contradictions[] fields, the meaning of hop and citation_uri, and performance expectations. It also covers prerequisites and failure modes, making it fully self-sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description does add meaning beyond the schema by explaining the practical impact of depth values ('so multi-step questions resolve in one call'), clarifying that questions can be broad/multi-part, and providing concrete example questions. However, the depth behavior is already well-described in the schema, so the added value is moderate rather than extensive.

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: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources... in ONE call'. It explicitly distinguishes from open-web search and from sibling ask_pipeworx, providing a specific verb, resource, and scope.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and direct alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also notes the account requirement and which tier supports depth:'thorough'.

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 covered. The description adds valuable disclosure about the return payload (top-N tools with full schemas, ready to call directly) and that no second lookup is needed – context beyond annotations that helps the agent set expectations.

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

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

The description is front-loaded with the core purpose, then gives a categorized usage context, return format, and a clear action directive. The domain list is long but directly useful for guiding search queries, and every sentence earns its place without fluff.

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

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

With no output schema, the description properly explains return values (tool names, descriptions, schemas) and convinces the agent that results are directly callable. Combined with the schema examples and usage guidelines, this makes the tool fully self-contained for an agent deciding 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?

Input schema covers 100% of parameters with descriptions, including aliases and limit defaults. The description does not add parameter semantics beyond the schema, so baseline 3 applies; the 'top-N' mention aligns with the limit parameter but adds no syntax detail.

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 with a specific verb ('Find tools' or 'discover what tools exist') and resource (tools by data/task). It distinguishes itself from sibling domain-specific tools by positioning as a meta-search for the tool catalog, and explicitly notes 'Call this FIRST' – a clear differentiator.

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 context for when to use: browsing/searching/discovering tools, with a domain list, and explicitly instructs 'Call this FIRST when you have many tools available.' It implies a when-not (if you already know the tool, use it directly) with 'not just one answer,' which serves as an exclusion signal.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond these: it lists the data sources fanned out (SEC, XBRL, USPTO, GLEIF, news), discloses the USPTO API sunset and soft-fail behavior, and describes return components with specific fields. This is rich operational transparency with no contradictions.

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

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

The description is a single dense paragraph, but every clause contributes: usage examples, data sources, output fields, fallback behavior, and parameter constraints. It is front-loaded with example queries. Slightly long but acceptable given the tool's complexity; no filler sentences.

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 covers what the tool returns (cik, filings, fundamentals, patents, news, LEI) and how it behaves (parallel call, fallback chains, soft-fail). Given the tool's multi-source complexity and only two parameters, this description is complete and self-sufficient.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds value by providing concrete examples ('AAPL', '0000320193') and reinforcing the rule that names are not supported—directing to resolve_entity. This goes slightly beyond the schema's baseline, warranting a 4.

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

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

The description clearly identifies the tool's purpose: producing a full cross-source profile of a US public company in one parallel call. It lists concrete outputs (cik, fundamentals, patents, news, LEI) and distinguishes itself from sibling tools by explicitly preferring over chained single-pack lookups. Examples ('Tell me about X', 'research Acme') make the intended use unmistakable.

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

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

Explicit guidance is provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' when a holistic view is requested. It also states when not to use the tool directly (if only a name is available, use resolve_entity first), and specifies accepted inputs (ticker or CIK). This fully addresses when vs. 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 flag destructiveHint=true and idempotentHint=true. The description adds context by mentioning clearing sensitive data, but does not disclose side effects beyond deletion (e.g., irreversibility) or any potential edge cases. With annotations covering the core safety profile, this is acceptable but not rich.

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

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

Two sentences, front-loaded with the primary action, and no filler. Every word contributes to understanding purpose and usage. Excellent conciseness.

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 trivial tool with one parameter, destructive hint, and no output schema, the description is sufficient. It covers what, when, and how to pair with siblings. It could mention that deletion is permanent, but the destructiveHint already implies this, so the completeness is high.

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

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

Schema coverage is 100% and the parameter 'key' is already described as 'Memory key to delete.' The description repeats 'by key' but adds no additional semantic detail (e.g., key format, case sensitivity, or behavior for missing keys). Baseline 3 is appropriate since 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 states a specific verb ('Delete') and resource ('previously stored memory by key'), which clearly distinguishes it from related tools like remember and recall. The purpose is 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?

Provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also names complementary tools ('Pair with remember and recall'), but does not explicitly state when not to use it or alternatives, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by revealing the process: fetches the page, extracts title/description/key links, and emits a text blob. This informs the agent about network access and output format 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?

Two sentences, front-loaded with the core purpose and method, followed by practical use cases. Every sentence earns its place with no 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 no output schema and good annotations, the description fully covers the tool's purpose, method, output format, and usage scenarios. It is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add parameter-specific details beyond what the schema provides; it only mentions 'any URL' and link extraction, which is already implied. No compensation needed.

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 has a specific verb 'Generate' and resource 'production-ready llms.txt file for any URL', clearly stating what the tool does. It distinguishes from siblings by specifying the exact outcome: a standard llms.txt markdown format ready for site-root deployment.

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 lists three concrete use cases: getting a client's site indexed, drafting for your own project, and auditing competitor AI presence. It does not mention alternatives or exclusions, but the usage context is very 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 and idempotentHint, covering safety. The description adds valuable context by listing exact return fields (id, type, params, created_at, last_fired_at, fire_count), which is useful for agents. 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, each earning its place. First states purpose and return fields, second gives usage guidance. Front-loaded and efficient with 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?

Despite lacking an output schema, the description fully explains what the tool returns. The optional parameter is documented in schema, and the use case is clearly stated. For a simple list tool with rich sibling context, this is complete.

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

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

Schema coverage is 100% for the single parameter include_inactive, so baseline is 3. The description mentions 'active subscriptions' which implicitly aligns with the default false, but it does not explicitly explain the parameter's meaning beyond the schema. No added value beyond schema, but no shortfall.

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 lists the caller's active subscriptions, which is a specific verb+resource pairing. It also differentiates from sibling tools like subscribe/unsubscribe by focusing on review/listing.

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: to review current monitoring before adding more or to find an id to cancel. This provides clear context and aligns with sibling tools, giving implied 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 only indicate non-read-only/non-destructive/null safety hints; the description adds substantive behavioral context: rate limits, free usage, claim_token creation and later lookup, daily digest review, and roadmap impact. There is no contradiction with 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?

Although the description is a long paragraph, it is front-loaded with the core purpose and every subsequent sentence adds actionable detail: usage rules, exclusions, content guidance, claim-token mechanics, and rate limits. No sentence feels wasted, and em-dash separators help group related ideas.

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

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

With no output schema, the description explains the claim-token return flow and the two invocation modes (submit feedback vs. check a prior report). It does not explicitly state what a successful submission returns when the user is authenticated, leaving a minor return-shape ambiguity. Otherwise, it is thorough enough for correct selection and invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful extra semantics beyond the schema, especially for claim_token (exact call pattern and what it returns) and message content guidance ('don't paste the end-user's prompt'). It does not add much beyond the schema for type/context, but the added parameter workflow detail justifies a 4.

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

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

The description opens with a concrete action—telling the Pipeworx team something is broken, missing, or needs to exist—and specifically names the feedback categories. It clearly distinguishes itself from sibling tools like ask_pipeworx by focusing on reporting issues about Pipeworx tools rather than retrieving information.

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

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

The description gives explicit when-to-use guidance (bug, feature, data_gap, praise), explicit when-not-to-use guidance (tools from other MCP servers, end-user prompts), and directs uncertain agents to use the Pipeworx tool list. This is exemplary usage guidance.

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description adds valuable behavioral context: the data source ('derived from CF analytics-engine'), privacy ('no PII'), the output shape ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). 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 four sentences, front-loaded with the core purpose, then use cases, then data provenance and caching. Every sentence adds useful information with no redundancy or fluff, though it is slightly longer than the two-sentence ideal.

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 tool with one optional parameter and no output schema, the description sufficiently covers what it returns, when to use it, data source, privacy, and caching. It does not detail the exact return structure beyond '(pack, tool, count)', but this is adequate given the simplicity of the tool.

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

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

The input schema already provides full description for the only parameter `window`, including its enum values and semantics about short vs long windows. The tool description merely repeats '24h, 7d, or 30d' without adding new meaning, so with 100% schema description coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d)', providing a specific verb and resource. It is inherently distinct from siblings by focusing on trending agent calls, but it does not explicitly name an alternative tool for comparison.

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 lists three concrete use cases: 'discovering what data sources are hot for current events', 'confirming a popular tool is the canonical choice before asking your own question', and 'seeing whether your use case aligns with what most agents need'. This gives clear context for when to use it, though it lacks explicit exclusions or alternative tool suggestions.

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 the description adds substantial context: scan scope (top ~200 markets), semantic anchor threshold (≥0.30 Jaccard), partition placeholder filter (>20% yields null), and fill-check behavior (prices against live CLOB depth, 1000 shares/leg). 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 lengthy but tightly structured with bold section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It front-loads the core purpose and usage, and every sentence carries operational information, though it could be slightly more concise.

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

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

With no output schema, the description defines the response shape (opportunities[], partition_check, skipped_low_similarity) and edge cases (null arb signal, thin legs). It covers invocation modes, filters, and fill-check caveats, making it sufficient for an agent to select and call 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 descriptions already cover both params, but the description enriches them with concrete slug examples ('fed-decision-may-2026'), topic seeds, and behavioral differences between event and topic modes. It also confirms that full Polymarket URLs are accepted, reinforcing 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+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by naming the arbitrage focus and explicitly invoking the fill check.

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 mode selection: 'event (recommended for a specific market)' vs 'topic (for cross-event scanning),' with concrete examples. It also directs custom sizing to 'polymarket_fill_risk' and warns when not to trade ('realizable_edge_pp ≤ 0 ... do not trade it'), giving clear when-to-use and when-not-to guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses extensive behavioral details: five model families, exact response segments, edge_pp_net after slippage, Kelly fractions, liquidity filters, a 24h-move warning, diagnostics for empty segments, and 1h KV-level caching. This greatly exceeds what annotations alone convey.

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

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

The description is dense but well-organized with uppercase section labels, and every sentence adds value. It avoids redundancy with the schema, instead providing context (e.g., slippage rationale, model family explanations). No filler or 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?

With no output schema, the description fully explains return structure: by_segment fields, fed_candidates/fed_note, and _diagnostics with funnel counters. It also explains edge cases like empty segments and the unreliability of Fed signals without paid data, making the tool's behavior predictable.

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

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

Although schema coverage is 100%, the description adds cross-parameter context and rationale. It groups knobs as 'TRADEABLE-EDGE KNOBS' and explains how min_liquidity/max_spread_pp drop unrealizable edges, and how min_partition_leg_kelly applies to per-leg Kelly inside top_legs, which is not obvious from the schema alone.

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

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

The description states a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is clearly differentiated from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx data disagreements and the 'what should I bet on today' use case.

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

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

The description provides clear context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains the tool's purpose and even notes exclusions (Fed bets excluded from ranking), but it does not explicitly name alternative tools or state when not to use this tool, so it stops 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 only declare read-only, idempotent, and non-destructive properties. The description adds substantial behavioral context: the 60-day snapshot TTL limits history depth, snapshots are written only on cache-miss (gaps indicate no scan), and decay is computed from daily closes of edge_pp_net (net of default slippage), not intraday. This goes well beyond the annotations.

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

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

The description is lengthy but meticulously structured: it opens with purpose, then details the args, response fields (tracked[], expired[], snapshot_dates[]) each with clear explanations, and ends with limits. Every sentence serves a purpose, and bold labels improve parseability for agents. It is as concise as the complexity allows.

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?

Since there is no output schema, the description carries full responsibility for explaining return values. It comprehensively describes all three response components, including the time-series, trend and decay fields, lifespan, and snapshot dates. It also covers the TTL and data-gap limitations, making the tool's behavior fully predictable for an agent.

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

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

Schema coverage is 100% (both params described), so the baseline is 3. The description adds meaning by explaining 'window (snapshot family)' and clarifying days as 'lookback' with 'max 30' vs schema's 'clamp 2-30'. While the min clamp is omitted in the description, the overall context adds value without contradicting the schema.

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

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

The description opens with a clear statement of the tool's role: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It further answers a specific question ('how long has this edge existed and is it shrinking?') and explicitly differentiates from the sibling polymarket_edges tool by focusing on historical snapshot analysis rather than current edge generation.

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 usage context by contrasting fresh vs. old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'), making clear when this tool should be used. However, it does not explicitly name alternative tools or provide exclusion criteria, 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 mark the tool read-only, but the description adds behavioral detail: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), and identifies thin legs and forced directional risk. It also reveals the auto side selection logic in basket mode, going well beyond the safety hints.

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

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

The description is dense but well-structured, front-loaded with the core purpose and then branching into modes and usage. While lengthy, each section adds essential detail for a two-mode tool, and the final sentence justifies use 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?

Given no output schema, the description enumerates key return fields like top_of_book, vwap_fill_price, capture_ratio, and verdict. It also covers both operating modes, edge-case behavior (partial fills), and provides use-case context, making it self-sufficient for an agent.

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

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

Schema coverage is 100%, but the description adds meaning by explaining how parameters interact—e.g., 'REQUIRES one of market or event' and the dual interpretation of size_usd (spend/proceeds vs settlement notional). This goes beyond the schema's field-level descriptions by clarifying the mode-dependent roles.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' clearly identifying the tool as a fill-risk checker. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on execution feasibility rather than opportunity detection.

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 text explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' naming the exact sibling tools. It also explains why—theoretical overround on thin books is not capturable and partial fills create unhedged positions—providing clear situational guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds substantial behavioral disclosure: compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs both >5 legs), temporal_alignment field and its implications, skipped_cross_type/subtype counters, and a candid note that most pre-mapped topics are not tradeable. This far exceeds 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 long but every sentence earns its place. It front-loads the core purpose and then systematically covers modes, response structure, and safety fields using clear formatting ('TWO MODES', 'SAFETY FIELDS'). No filler or redundancy; it's 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 compensates by detailing the response: leg-by-leg prices (raw 0-1), matched spread[].top_spreads_pp, compatibility_warning conditions, temporal_alignment with aligned flag, and skipped_cross_type/subtype. It covers all necessary operational edge cases for a cross-venue tool, making it complete.

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

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

Schema coverage is 100% with descriptions for all three parameters, but the description adds meaningful context: explains how topic auto-fetches matching events, how explicit ticker/slug override the mapped side, and how the response's top_spreads_pp is calculated. The modes give parameters a conceptual framework beyond bare field 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 immediately states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, which is a specific verb+resource+scope. It clearly distinguishes this from siblings like polymarket_arbitrage and polymarket_edges by emphasizing cross-venue comparison and spread calculation.

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 describes two modes (topic shortcuts vs explicit ticker/slug), explains when each should be used, and provides critical usage warnings: pre-mapped shortcuts often return compatibility_warning and pre-mapped ≠ tradeable. This goes beyond simple context to give actionable 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, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond these: the scoping detail ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the behavior of listing all keys when the key argument is omitted. This enriches agent understanding of the tool's operational boundary.

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 composed of four sentences, each earning its place: core action (first sentence), use cases (second), scoping (third), and sibling relationship (fourth). It is front-loaded with the main verb and contains 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 read-only tool with one optional parameter, strong annotations, and no output schema, the description covers purpose, usage scenarios, scoping, and related tools. It does not specify return format or error behavior, but the tool's low complexity and rich annotations make this a minor gap rather than a critical omission.

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%: the only parameter 'key' already has a description ('Memory key to retrieve (omit to list all keys)'). The tool description reinforces this with examples and restates the omit-to-list behavior, but adds no new syntax, format, or edge-case details beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's action with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys'. It explicitly distinguishes between retrieval and listing, and names sibling tools (remember, forget), which differentiates it from alternatives.

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 context: 'Use to look up context the agent stored earlier' and gives concrete examples (target ticker, address, research notes). It also names alternatives by saying 'Pair with remember to save, forget to delete', which clarifies when to use this tool versus its siblings.

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 Contradiction: readOnlyHint=true conflicts with the description's statement that 'Set mark_read:true to flag returned events read so the next call only shows newer ones' — this implies persistent state mutation. While the description otherwise discloses payload contents and feed behavior, the contradiction with the read-only annotation forces a score of 1.

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

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

Four concise, front-loaded sentences cover purpose, return payload, filtering, side effects, and polling suitability. Every sentence earns its place 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?

Despite no output schema, the description explains what each event carries (source, citation_uri, raw payload) and how the tool behaves (filtering, mark_read side effect, polling). Parameters limit and unread_only are adequately covered by the schema, so the description is complete for this tool's complexity.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds value by giving a concrete type example ('sec_8k') and clarifying the consequence of mark_read (next call shows only newer events), going beyond the schema's short 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 'Pull fired events from your subscription feed', a specific verb and resource. It distinguishes this tool from siblings like list_subscriptions and recent_changes by focusing on fired alert events with payload 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?

Provides clear context: filtering by type and/or since, polling suitability ('Polls work fine'), and an alternative access method via a direct URL. It stops short of explicitly naming sibling alternatives or stating when not to use this tool, so it misses 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 discloses multi-source fan-out, GDELT→GNews fallback on rate limits/5xx, and the PatentsView API sunset causing soft-fail, which goes beyond the readOnly/idempotent annotations. It also describes the return structure (changes[], total_changes, citation URIs), providing a comprehensive behavioral model.

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?

While longer than two sentences, the description is well-organized and dense with useful information, avoiding repetition. The opening query examples are front-loaded for quick relevance matching, and the later sections on sources, parameters, and alternatives each add necessary context.

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 trigger phrases, source behaviors, parameter options, output structure, and the key alternative tool, which is sufficient given the absence of an output schema. It even notes external API limitations, making it robust for an agent to set expectations.

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 covers all three parameters with detailed descriptions, including `since` format examples and the 30d/1m recommendation, so the description adds no new parameter meaning. Baseline 3 is appropriate given 100% schema coverage; any extra is redundant.

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

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

The description clearly defines the tool as a change feed aggregating SEC/GDELT/GNews/USPTO data for a company over a time window, triggered by natural-language queries like 'What's new with X'. It differentiates from entity_profile by explicitly naming the alternative, making its 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?

It provides explicit when-to-use signals via example queries and states when to use entity_profile instead, giving a clear exclusion criterion. It also explains the parallel fan-out and fallback behavior, helping the agent decide based on user intent.

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 a write operation (readOnlyHint=false) and safe repetition (idempotentHint=true). The description adds persistence details: identifier scoping, 24-hour retention for anonymous sessions, and persistent memory for authenticated users. It does not list failure modes or overwrite behavior, but the additional context is beyond annotations.

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

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

Five sentences, each providing distinct value: action, use-case, storage format, persistence policy, and sibling relationships. No redundant phrases.

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

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

Covers purpose, when to use, storage mechanics, retention, and integration with recall/forget. No output schema is defined, so no return-value explanation is required. Simple two-string tool is fully addressed.

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

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

Schema covers 100% of parameters with detailed descriptions and examples. The tool description adds general usage context but no new parameter-specific semantics; 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 uses the verb 'save' with a clear object ('data the agent will need to reuse later') and explicitly names sibling tools 'recall' and 'forget' to differentiate retrieval and deletion. This distinguishes it from the 30+ sibling tools.

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

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

It states when to use ('when you discover something worth carrying forward'), provides concrete examples, and says 'Pair with recall to retrieve later, forget to delete,' explicitly mapping alternatives. This goes beyond implied usage into 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, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context beyond this: graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), cascading internal lookups ('replaces 2-3 manual lookups'), labeling of identifiers with source, and explicit handling of unresolved identifiers under an 'unresolved' field. This fully informs the agent about runtime behavior and failure modes.

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

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

The description is front-loaded with examples and a clear purpose statement, which is good. However, it is lengthy (over 150 words) and contains some redundancy (e.g., 'every identifier is labelled with the source that established it' restates the structure of the output). It could be more tightly edited while retaining all information. A score of 3 reflects adequate but not optimal conciseness.

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 fully documents what the tool returns for each entity type: for company (CIK, ticker, company_name, LEI with ownership, FIGI, unresolved identifiers), for drug (RxCUI, ingredient, brand, citation). It also covers error handling (graceful degradation) and internal complexity (cascading lookups). No missing context for correct invocation or understanding return values.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning: for 'type' it explains the two enum values with what each returns (company: CIK+ticker+LEI+FIGI etc.; drug: RxCUI+ingredient+brand). For 'value', it expands on acceptable inputs (ticker, CIK, ISIN, name for company; brand/generic for drug) and even explains how an ISIN resolves via GLEIF. This goes well beyond the schema's short descriptions, justifying a 4.

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

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

The description opens with concrete example queries ('What's the ticker for...', 'find the CIK for...'), then explicitly states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes itself from sibling tools like 'entity_profile' by instructing to 'Use FIRST whenever you have a name but need an ID.' This makes the tool's role unambiguous and singular.

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

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

The description provides clear when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It gives extensive examples of user queries that trigger this tool. While it doesn't explicitly name sibling tools to avoid (e.g., 'entity_profile' is for after you have an ID), the context is strongly implied. The phrase 'replaces 2-3 manual lookups' also sets expectations. A slight deduction for lacking explicit 'when NOT to use' statements.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds that it performs a multi-probe comparison via ai_visibility_check and returns a ranked summary, which goes beyond the annotations and clarifies the internal process.

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

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

Four concise sentences: purpose, mechanics, use case, and output format. Every sentence earns its place, with no repetition 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 tool with only 4 params and no output schema, the description covers the behavior, return format (ranked list with score/confidence/signal density), and use case. Combined with rich annotations and schema, it 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 description coverage is 100% with detailed parameter docs, including supported models, optional API key, shared context, and entity ordering semantics. The description reinforces the 'brand + competitors' idea but adds no extra parameter meaning beyond the schema.

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

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

Clearly states the tool compares AI visibility across entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. This specific verb+resource+outcome distinguishes it from sibling tools like ai_visibility_check (single probe) and compare_entities (generic comparison).

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 frames usage for competitive AI-marketing audits and provides a concrete example question. While it doesn't name alternative tools or exclusions, the context is specific and actionable, making it easy to decide when to use.

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 cover read-only and idempotent hints, but the description adds valuable behavioural context: it fans out across two services, partial failures degrade gracefully, and a 5-30s timing risk for bundlephobia's first measurement. This goes well beyond what annotations convey.

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

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

The description is dense but every sentence adds value: it front-loads the core purpose, lists key outputs, notes ecosystem limitations, and explains failure handling. No pointless 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 composite tool with no output schema, the description covers all essential aspects: what it does, when to use it, what it returns, failure modes, and ecosystem scope. It is fully adequate for an agent to select and invoke correctly.

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

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

The schema already provides 100% coverage with descriptions for both parameters (package name and version). The description adds minimal extra semantics (e.g., example 'lodash'), and does not clarify defaults or formats beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states this is a composite 'should I add this npm package' check, naming both deps.dev and bundlephobia. It is specific about the resource and scope, and distinguishes itself from sibling tools by being the only npm-focused dependency scanning tool.

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

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

Explicit usage guidance is given: 'Use whenever an agent asks "is X safe / popular / small"...' It also provides a clear exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' effectively naming the alternative.

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 readOnlyHint/openWorldHint/idempotentHint, but the description adds substantial behavioral context: truncation at 200K chars with flagging, embedding model (BGE-base-en), overlapping windows, and output includes offsets and similarity scores. This exceeds the baseline set by annotations.

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

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

The description is front-loaded with the core action, then use case, pairing, and technical details. Every sentence provides distinct value—no fluff. Length is appropriate for the complexity, and structure moves from high-level to implementation specifics.

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 covers return values (passages with offsets and similarity scores), input constraints (200K chars), usage context, and technical behavior. It fully equips an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics: clarifies 'text' is 'already pulled' content (not a URL/id), gives query examples ('supply-chain risk'), and explains limit as top-N passages. This goes beyond the schema's brief descriptions, justifying a 4.

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

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

The description uses a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from siblings like ask_pipeworx by emphasizing it operates on text you already pulled, and explicitly pairs with ask_pipeworx_grounded. The scope is unambiguous and actionable.

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

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

States exactly when to use: 'Use when the record is too big to cram into the prompt.' Also provides an alternative workflow with ask_pipeworx_grounded, and explains benefits (saves context, verifiable quotes). This is explicit usage guidance with a named alternative.

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 Contradiction: The description says 'Returns the new subscription id,' implying a fresh subscription is created on each call, while annotations declare idempotentHint=true, which means repeated identical calls should not create duplicate resources. This is a direct contradiction. The description also does not clarify deduplication behavior or whether an existing subscription ID is returned on retry.

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

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

The description is dense but well-structured: it opens with the core purpose and auth requirement, then systematically covers supported types with examples, and finally explains delivery channels. Every sentence carries necessary information, and the front-loading is effective.

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

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

The description is highly complete for a create operation: it covers auth requirements, return value, supported types, delivery options, and operational constraints (verification, caps, auto-disable). The only notable gap is the lack of clarity around idempotency, which is also the source of the annotation contradiction, so it does not fully achieve a 5.

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

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

Although schema coverage is 100%, the description adds substantial value beyond the schema by providing concrete examples for each subscription type (e.g., items:["5.02"], topic:"fed", series_id:"UNRATE"), and detailing delivery constraints (verified phone, 10/day cap, webhook signing secret). This goes far 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+resource: 'Create a proactive monitoring subscription to a live-data event stream.' This clearly distinguishes it from siblings like 'list_subscriptions', 'unsubscribe', and 'recent_alerts' by focusing on the creation action and the target resource.

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

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

The description provides clear context for when to subscribe, enumerates supported types, and even references 'recent_alerts' for pulling from the always-on feed. It does not explicitly say 'use this instead of X' or list exclusions, but the context is sufficient for an agent to decide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, and the description adds substantial behavioral context: the output structure (category-bucketed examples with tool+argument shapes), that it is drawn from a live catalog of thousands of tools, and how invocation with or without `topic` changes results. 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 dense and front-loaded, with every sentence contributing either example queries, return behavior, or usage guidance. The list of categories is long but informative; minor verbosity in the opening example string is acceptable given the tool's onboarding purpose.

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

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

For a tool with one optional parameter and no output schema, the description fully covers purpose, behavioral details, invocation patterns, and parameter semantics. It gives the agent enough to understand expected response structure and when to use it, especially in context of sibling meta-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?

The schema covers the single optional `topic` parameter with a list of values, and schema description coverage is 100%. The description reinforces parameter meaning with examples ('finance', 'pharma', 'betting') and explicitly explains the behavior when omitted (full spread), adding value beyond the schema.

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

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

The description clearly states the tool's role as the onboarding entry point, lists example user queries, and explains it returns category-bucketed example questions with exact tool and argument mappings. It distinguishes itself from siblings by explicitly naming meta-tools and positioning itself as the first thing to use.

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

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

The description gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also names alternative tools (ask_pipeworx, entity_profile, compare_entities) to learn how to call them, providing clear context on when this tool is appropriate versus alternatives.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true), the description discloses that ownership is enforced and that the row is deactivated rather than deleted, preserving historical events. This adds significant behavioral context.

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

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

Two sentences, no fluff. The action is front-loaded and each sentence provides essential information about cancellation, ownership, and the soft-delete behavior.

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

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

For a single-parameter tool with annotations and no output schema, the description covers purpose, ownership, side effects, and connection to recent_alerts. It is sufficiently complete for correct invocation.

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

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

The schema already describes the id parameter as a subscription uuid from subscribe. The description simply refers to 'by id' without adding further parameter semantics. Baseline 3 is appropriate given 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 cancels a subscription by ID, using a specific verb and resource. It distinguishes from siblings like subscribe and list_subscriptions, and adds ownership and deactivation 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?

Provides clear context on ownership enforcement and the deactivation behavior, implying when it should be used (for canceling one's own subscriptions). However, it does not explicitly name alternatives or exclusions, 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?

Even with readOnlyHint=true and other annotations, the description adds critical behavioral context beyond them: it explains the meaning of the verdict 'could_not_verify' (not evidence, must not be shown as one) and the distinction between 'could_not_verify' and 'unsupported'. It also reveals the two-path pipeline (structured vs. grounded) and that it returns a value with citation and reasoning. This is substantial transparency.

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

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

The description is lengthy but well-structured: it opens with trigger phrases, states the core purpose, differentiates the two verification paths, lists output components, and highlights an important caveat with a bolded 'IMPORTANT' callout. Every section serves a purpose, though some redundancy exists between 'natural-language claim verification' and 'check whether something a user said is factually correct'.

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

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

Given the tool's complexity (two complex parameter types, no output schema, multiple possible verdicts), the description is thorough: it specifies when to use, the internal routing logic, the exact verdict list, and the semantics of ambiguous verdicts. This fully equips an agent to decide when to call it and how to interpret the result, making it nearly 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 input schema alone describes both parameters with clear descriptions and examples (100% coverage). The description does mention 'exact percent-delta math' and tolerance concepts indirectly, but it does not add any new parameter-level semantics beyond what the schema already provides. Baseline of 3 is appropriate since 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 clearly identifies the tool as a claim-verification tool with specific verb phrases ('verify the claim that...', 'fact check') and resource ('natural-language claim verification against authoritative sources'). It explicitly differentiates from sibling tools by outlining the fast path for financial claims and the grounded pipeline for other claims, and it even notes it replaces 4–6 sequential calls. This makes the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance ('Use whenever the agent needs to check whether something a user said is factually correct') and clarifies the routing between financial and non-financial claims. However, it does not name any alternative tools or explicitly state when not to use this tool, so it lacks the exclusionary guidance needed for a 5.

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