Colombia Secop

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

Annotations already declare read-only, open-world, idempotent, non-destructive behavior. The description adds useful context beyond annotations: default model (Workers AI Llama-3.3-70b), cost implications ('BYO key — you pay Anthropic directly'), and return structure. 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 concise (three sentences) and front-loaded with the core purpose. Each sentence adds value: function, model options/cost, return format, and use cases. No unnecessary detail or repetition.

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

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

Despite having no output schema, the description explicitly states the return shape ('per-model {score, confidence, signals, raw_response} + a combined view'), which compensates. It covers inputs, defaults, costs, and use cases. The tool is well-specified for its complexity with 4 params and no nested objects.

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

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

Schema description coverage is 100%, and all four parameters are well-described in the schema. The description reiterates the default model and _apiKey usage but does not add substantial new meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states a specific action ('Probe one or more LLMs') and the resource ('business / brand / product / topic'), with a concrete output ('score visibility (0-100) per model'). It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on direct LLM probing and scoring rather than scanning presence.

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

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

The description provides clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains model selection and API key usage. It does not explicitly contrast with alternative tools, but the context is clear enough for an agent to infer when to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds meaningful behavior beyond that: it routes to 5,564 tools, returns 'the structured answer with stable pipeworx:// citation URIs', and is framed as a fast single call. 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 long, but every sentence contributes value: preference over web search, coverage scope, routing behavior, trigger phrases, examples, and escalation alternatives. It is front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and structurally organized.

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

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

With no output schema, the description fully compensates by explaining expected output ('structured answer with stable pipeworx:// citation URIs'), input expectations via examples, and clear boundaries (when to use alternatives). It is complete enough for an agent to select and invoke this broad routing tool effectively.

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

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

The schema has 100% coverage for all 6 parameters (question plus five aliases), each documented. The description adds context about the kind of natural-language input expected (e.g., examples), but no additional parameter syntax or value constraints. Baseline 3 is appropriate given full schema coverage.

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

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

The description opens with 'PREFER OVER WEB SEARCH for questions about current or historical data' and clearly states the tool 'Routes the question to the right one of 5,564 tools across 1462 verified sources'. It lists concrete domains, examples, and distinguishes itself from ask_pipeworx_grounded and deep_research, making the purpose unmistakable.

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

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

Provides explicit usage guidance: 'START HERE for most questions — this is the default entry point, works on every tier, one fast call' and 'Step up only when needed' with named alternatives (ask_pipeworx_grounded, deep_research). It also includes trigger phrases and examples, making when-to-use vs. alternatives clear.

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

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

Annotations already declare readOnly, openWorld, and idempotent. The description adds valuable context about beta behavior (candidate routing improvements, current null state) and confirms it's fully functional. 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 informative but slightly wordy. It front-loads the core purpose and clearly structures the beta status and usage guidance. Every sentence adds value, though it could be tightened without losing 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?

No output schema exists, but the description references the same response shape as ask_pipeworx, relying on external knowledge. Given the tool's beta nature and sibling context, this is sufficient. The complexity is moderate, and the description covers the key 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?

Schema covers 100% of parameters with clear descriptions. The description adds no extra parameter detail beyond mentioning 'same arguments' as ask_pipeworx, which is external. Baseline 3 is appropriate given complete 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 it's a beta version of ask_pipeworx, a universal router with identical functionality. It distinguishes itself from siblings by explicitly naming the stable router and the beta nature, providing a specific verb ('ask') and resource ('pipeworx beta').

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains the testing context. It also clarifies that it's a full working router, not a fallback, giving clear when-to-use guidance without ambiguity.

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

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

Beyond annotations (readOnly, openWorld, etc.), the description discloses internal workflow: routing, argument filling, fetching, extraction, and explicit refusal reasons with a structured JSON response. It also mentions the extra LLM call cost, offering deeper behavioral insight.

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

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

Five sentences, each adds value: purpose, mechanism, return format, refusal reasons, usage guidance, and cost tradeoff. Front-loaded with the core idea, no filler or repetitive content.

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

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

The tool is complex (routing, extraction, refusal handling), but the description provides the return shape, refusal codes, and usage boundaries. It fills gaps left by the absence of an output schema, making it self-sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% (all parameters are aliases and described), so the description adds no extra parameter detail. The baseline of 3 applies because the schema already carries the semantic load, and there is no need for compensation.

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

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

Description clearly defines the tool as a 'hallucination-resistant answer mode' for high-stakes reads, contrasting with ask_pipeworx by extracting answers only from tool results. It names the specific verb ('EXTRACTS') and resource (tool result), making its purpose unambiguous.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also provides a direct alternative: 'prefer ask_pipeworx for casual lookups,' including a cost–benefit tradeoff.

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, open-world, and non-destructive. The description massively adds behavioral context beyond that: resolver contract (market_match_confidence, score, alternatives), safety short-circuits (low_confidence_match, market_closed_or_inactive), illiquid_wade_spread flag, resolution-rule risk (cancellation_rule with examples like refund_50_50), news fallback behavior (fallback_attempted, retry_after_sec), and even a warning about model edge being priced in. This is exemplary transparency.

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

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

The description is long but every sentence is purposeful and packed with relevant behavior. It is front-loaded with the core purpose in the first line, then uses CAPITALIZED section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) to make information navigable. There is no filler; the complexity of the tool justifies the length.

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

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

With no output schema, the description must fully explain what the tool returns. It does this thoroughly: result.market fields, result.analysis with model probability and edge warning, result.evidence keying, resolver contract with match confidence and alternatives, parent_event extractor for elections/championships, news fallback fields, and safety statuses. It even covers edge cases like low-confidence, closed markets, and wide spreads. This is complete enough for an agent to confidently invoke the tool.

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

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

Schema description coverage is 100% and all three parameters have clear descriptions in the input schema. The tool description reinforces the market parameter formats (slug, URL, question text) and adds context about depth and include_raw via the schema itself, but beyond that it does not add new parameter-level semantics. Baseline 3 applies because the schema already does the heavy lifting.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling tools like polymarket_edges or plymarket_arbitrage by focusing on bet research and evidence gathering, not just edge detection or arb. The scope is explicit: accepts slug/URL/question text and returns a structured evidence packet.

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

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

The description explicitly states the intended use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This is strong when-to-use guidance. However, it does not explicitly mention when NOT to use this tool or name alternative sibling tools for different purposes, so it misses the 'when-not/alternatives' part that would earn 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 read-only, idempotent, non-destructive behavior; the description adds valuable context about full-text matching, Spanish language best practices, the effect of omitting the query, and the specific output fields. It does not contradict annotations and enhances behavioral understanding.

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 appropriately sized and well-structured, leading with the core purpose, then usage guidance, parameter behavior, and return fields. Every sentence adds value without redundancy, and it is front-loaded with the most critical 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?

With no output schema, the description must explain return values, and it does so by listing the exact fields (contract id, object, entity, supplier, value, type, modality, status, signing date). It also covers data source and language, making the tool's complete behavior clear for an agent to invoke correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description provides extra semantics: it explains that query matches the contract object/description in Spanish, and that omitting it returns recent contracts. This goes beyond simple schema descriptions, though it does not fully compensate for all nuance (e.g., limit semantics already in 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 searches Colombian government awarded contracts, with specific source (SECOP II, datos.gov.co) and explicitly differentiates from web search by listing targeted use cases. It is a specific verb+resource+scope, and the mention of 'AWARDED CONTRACTS' distinguishes it from similar siblings like colombia_search_processes.

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 'PREFER OVER WEB SEARCH' guidance with concrete example query types ('who won...', 'awarded to...', 'spending...'), and explains when to omit the query for recent contracts. This gives clear when-to-use direction and notes the alternative (web search), satisfying the dimension fully.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). Description adds meaningful context: full-text query behavior, omission behavior, output row structure (process id, entity, prices, award value, supplier, etc.), and that values are in Spanish. This goes beyond annotation basics.

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

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

Description is moderately sized but well-structured: purpose first, usage guidance, query semantics, and output summary. Each sentence adds value, though it could be slightly more concise by merging a few 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?

No output schema exists, so the description compensates by enumerating the returned fields (process id, name, entity, base price, award value, supplier, contract type, modality, status, publication date). It also notes language and source. This is sufficient 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?

Schema already documents all parameters with 100% coverage, so baseline is 3. Description adds semantics for 'query' (full-text match, Spanish works best, omit for most recent) and hints at entity filtering. This enriches parameter understanding beyond 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?

Clear action ('Search'), specific resource ('Colombian government procurement TENDERS (SECOP II "Procesos de Contratación")'), and data source ('datos.gov.co'). It distinguishes itself from the sibling 'colombia_search_contracts' by explicitly referencing SECOP II tenders/procesos.

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 prefer this tool over web search with concrete example queries. It gives guidance on omitting query for recent processes, but does not contrast with the sibling 'colombia_search_contracts' or mention when not to use this tool.

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

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

Beyond the readOnly and idempotent hints, the description details data sources (SEC EDGAR/XBRL, FAERS), behavior (off-calendar fiscal years handled, results sorted by primary metric), and output format (paired data + citation URIs). This adds substantial behavioral context 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?

The description is dense but every sentence serves a purpose: examples, usage rule, type-specific details, sorting behavior, and output. It's long but appropriately structured for a tool with two entity types and multiple data sources. 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?

For a tool with no output schema, the description fully covers what the agent needs to know: input limits, type-specific data points, sorting, and return format with citation URIs. It also explains why it's better than alternatives, making it self-contained.

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

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

Schema covers both parameters at 100%, but description adds meaning by explaining what each 'type' returns and gives examples for 'values' (tickers/CIKs vs drug names). It also clarifies the parallel nature and the limit of 2–5, reinforcing schema constraints with practical context.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs in one parallel call. It provides specific example queries ('Compare X and Y', 'rank these companies') and explicitly distinguishes from sequential single-entity lookups, unlike sibling tools like entity_profile.

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

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

It gives explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and mentions it replaces 8–15 lookups. It does not name specific sibling tools but provides clear when-to-use context. Missing explicit 'not for single entities' but that's 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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral context: account requirements, paid plan for thorough depth, expected latency (15-60s, up to 90s), how it decomposes into facets, parallel tool routing, returns verbatim evidence with confidence and citations, gap handling (never invented), contradiction scanning, semantic excerpting, and guarantees that citations are always fetchable. This far exceeds what annotations provide and does not contradict them.

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

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

The description is long but front-loaded with the most critical info (account requirement, alternative tool). Each sentence adds value: it explains the architecture, output format, time expectations, and edge cases. While verbose, it is logically structured into paragraphs and avoids redundancy. Some trimming could improve conciseness, but the density is justified given the tool's complexity.

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

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

With no output schema, the description carries full responsibility for explaining return values. It thoroughly covers the findings packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field), the citation resolvability, and the semantic excerpting behavior. Combined with annotations, this is a very complete description for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds significant meaning. For depth, it explains the differences between quick/standard/thorough in detail (number of facets, gap recovery, contradiction scan, iterative hops). For question, it emphasizes that broad/multi-part questions are fine and that decomposition is the tool's core purpose. This goes well beyond the schema's bare descriptions.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' and specifies it is for broad/multi-part questions. It explicitly distinguishes from ask_pipeworx by noting 'this is NOT open-web search' and that ask_pipeworx is for single lookups, so it differentiates well from siblings.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and contrasts with ask_pipeworx for single lookups and breaking news. Also gives clear account requirements and alternatives (use ask_pipeworx if not signed in), making usage conditions unambiguous.

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

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

Beyond the readOnly, idempotent, and non-destructive annotations, the description discloses key behavioral traits: it returns 'the top-N most relevant tools' with 'names, descriptions, and full input schemas (with curated examples),' and each result is 'ready to call directly, no second schema lookup needed.' This adds significant actionable context about output format and efficiency, exceeding what annotations provide.

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

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

Three sentences deliver purpose, domain scope, return behavior, and usage timing in a front-loaded, structured way. The long list of domains is relevant and serves as a quick reference, while every sentence earns its place without redundancy. It is appropriately sized for a tool that covers many data categories.

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 meta nature and lack of an output schema, the description sufficiently covers its role: what it takes (a task description), what it returns (tools with schemas and examples), and how to use it in a broader workflow ('Call this FIRST'). It also enhances completeness by listing supported data domains, making it a comprehensive self-contained guide for selecting and invoking 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 has 100% coverage with descriptions for all 6 parameters, including aliases and the 'limit' parameter. The description adds little beyond confirming the query is a natural language description and mentioning 'top-N' matching 'limit.' Since the schema already carries the semantic weight, the description provides no additional parameter meaning, aligning with the baseline 3.

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

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

The description begins with a specific verb and resource: 'Find tools by describing the data or task.' It clearly distinguishes this from sibling tools by positioning it as a meta-tool for discovering other tools, listing covered domains, and stating 'Call this FIRST when you have many tools available.' This is not a tautology and fully differentiates it from the other 32 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?

Explicit usage guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' While it doesn't name a specific alternative, the heuristic 'not just one answer' implies when to bypass it, and the 'FIRST' directive gives clear priority among many tools.

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

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

The annotations already declare readOnly, openWorld, and idempotent, so the description adds extra context: patents 'soft-fails until reactivated' due to USPTO API sunset, news uses 'GDELT→GNews fallback', and the tool fans out across multiple sources. This goes beyond the structured annotations.

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

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

The description is long but well-structured: it opens with example queries, states the purpose, then lists return fields and caveats in a compact, scannable format. Every sentence adds value, though it could be trimmed slightly.

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?

Without an output schema, the description carries the full burden of explaining return values, and it does so thoroughly: cik, company_name, recent_filings with URIs, fundamentals selection, patents status, news fallback, and LEI. It omits error handling for invalid tickers, but for a read-only multi-source profile it 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 coverage is 100%, and the schema already describes the 'company' enum and the ticker/CIK format with examples. The description repeats the same examples ('AAPL', '0000320193') and the resolve_entity note without adding new parameter semantics beyond the schema.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call' and includes concrete example queries. It distinguishes from siblings by explicitly preferring it over chaining single-pack lookups and naming resolve_entity for name-only inputs.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and 'use resolve_entity first if you only have a name'. This tells the agent when to use and when not to use the tool.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds that it deletes 'previously stored memory' and mentions clearing 'sensitive data,' which gives some behavioral context. However, most of the destructive behavior is already conveyed by the annotations, and the description does not add details about reversibility or failure outcomes.

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

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

The description is two sentences, front-loaded with the core action, and every clause adds value (usage context and related tools). There is no wasted wording.

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

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

For a simple single-parameter delete tool with annotations covering safety, the description is complete enough. It tells what the tool does, when to use it, and how it relates to other memory tools. The lack of output schema is acceptable since the tool is straightforward, though it could mention behavior for missing keys (but idempotentHint already implies safe no-op).

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 describes the single parameter 'key' with a clear description. The description repeats 'by key' but adds no extra semantic detail. With 100% schema description coverage, the baseline of 3 applies.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Delete a previously stored memory by key.' This directly distinguishes it from sibling tools like 'remember' and 'recall' by indicating the delete operation.

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

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

The description provides explicit use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with remember and recall, which gives context on related tools. However, it does not explicitly state when not to use the 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?

Discloses that it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This adds workflow context beyond the annotations (readOnly, idempotent) without contradicting them.

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

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

The description is three focused sentences: the main purpose, the process/output, and concrete use cases. It is front-loaded, concise, and 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?

For a simple tool with rich annotations and complete schema, the description covers the core behavior, output format, and usage scenarios. It does not delve into error handling, but that is not essential for this tool's context.

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

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

Schema covers both parameters (url, max_links) with descriptions, achieving 100% coverage. The description adds general context (e.g., 'any URL', 'key links') but does not provide additional parameter-specific semantics 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 the tool generates an llms.txt file for any URL and explains the process (fetch, extract, emit). It is specific and distinguishable by its focus on producing llms.txt, though it does not explicitly reference sibling tools for differentiation.

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

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

Provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context for when to use it. It lacks explicit exclusions or alternative tool names, but the guidance is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the bar is lower. The description adds value by specifying the return fields and scope ('caller's active subscriptions'), offering behavioral clarity 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 action and returns, followed by a usage tip. Every word earns its place; no fluff or repetition of schema/annotations.

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

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

The tool is simple (one optional parameter), has strong annotations, and the description lists return fields despite no output schema. It covers purpose, returns, and usage guidance, making it complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% for the single parameter include_inactive, which already explains its meaning and default. The description adds no additional parameter context, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, names the specific return fields, and contrasts with sibling tools like subscribe/unsubscribe. It answers both what it does and what resource it targets.

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 tells when to use it: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This references the sibling subscribe and unsubscribe tools, providing clear context and implicit 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?

With all annotations false, the description carries full responsibility for behavioral disclosure. It reveals rate limiting (5/day), that it's free and doesn't count against quota, the daily digest cadence, and the claim_token exchange for later status checks. This goes well beyond the minimal 'sends feedback'.

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

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

The description is longer than average, but every sentence adds unique operational value: purpose, when to use, when not to use, how to frame, claim_token mechanics, rate limit, and cost. The structure is front-loaded with the core action and flows logically to edge cases.

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

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

Despite the lack of an output schema, the description explains the primary return behavior (claim_token) and how to consume it later. It covers the tool's constraints (rate limit, scope) and provides enough context for an agent to decide when to file feedback. A short note on the exact response shape beyond the token would push this to 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?

The schema already covers 100% of parameters with descriptions, so the baseline is 3. The description adds valuable usage context for `message` (don't paste the user's prompt, be specific) and `claim_token` (how to read a reply). It also clarifies the purpose of the `context` object implicitly, though it doesn't rename any fields.

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 verb-object statement ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates the feedback categories. It differentiates from siblings by explicitly scoping to tools served by this Pipeworx connection and warning against using it for other MCP servers.

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

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

It states explicit trigger conditions for each feedback type and provides a clear negative case (tools from other MCP servers). It also advises on how to frame the message (in terms of Pipeworx tools/packs, not end-user prompts) and clarifies the claim_token workflow.

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

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

The description adds significant behavioral detail beyond the annotations: it discloses the data source (CF analytics-engine), privacy (no PII), output shape ((pack, tool, count)), and caching behavior (5min-1h depending on window). This goes well beyond the safety hints already present in annotations and enriches the agent's understanding of the tool's behavior.

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

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

The description is well-structured and front-loaded: the first sentence states the core purpose, followed by a concise bullet list of use cases and a compact factual note. Every sentence earns its place, and the total length is appropriate for the richness of 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 tool with one optional parameter, no output schema, and good annotations, the description covers all necessary context: what it returns, use cases, data source, caching, and privacy. It explains the output components ('top tools, top packs, total call volume') even without an output schema, making it complete for an agent to invoke correctly.

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

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

The input schema already describes the 'window' parameter fully, including enum values and the trade-off between shorter vs longer windows. The description mentions the window options but does not add new meaning beyond the schema. Baseline 3 is appropriate given 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 states the tool's function with a specific verb ('Returns') and resource ('top tools, top packs, total call volume over a recent window'). It clearly distinguishes this from sibling tools by focusing on aggregate trending data of AI agent usage, not individual searches or tool discovery.

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

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

The description provides three explicit use cases with bullet points, which is clear context for when to use the tool. However, it does not explicitly name alternative tools or state 'when NOT to use it', so it does not fully meet the highest bar for 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?

Beyond the read-only/idempotent annotations, the description discloses rich behavioral details: the partition filter drops placeholder slugs, deviations >3pp trigger signals, skipped_low_similarity reports rejection count, and the fill check prices against live CLOB depth with a clear 'do not trade it' instruction when realizable_edge_pp ≤ 0. No annotation contradiction; this significantly extends trust and safety understanding.

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 section (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) earns its place with dense, relevant information. It is front-loaded with the core purpose and immediately explains invocation modes, then layers behavioral details in a logical order without repetition or 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 fully compensates by enumerating response fields (opportunities[], partition_check, fill_check) and explaining edge cases (skipped_low_similarity, placeholders_filtered, thin_legs). It covers a complex multi-mode tool exhaustively, including failure interpretation and interaction with a sibling tool.

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

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

Although the schema already describes both parameters at 100% coverage, the description adds substantial semantic depth: it explains what each mode does, that event accepts slugs/URLs, that topic accepts seed questions, that no args triggers trending_scan, and gives concrete examples. This goes far beyond the schema's field descriptions.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this from siblings like polymarket_edges and polymarket_fill_risk by describing unique modes (trending_scan, event, topic) and explicitly referencing a sibling for custom sizing.

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

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

Usage guidance is explicit and comprehensive: 'Call with NO args for a trending_scan,' 'pass event,' and 'pass topic.' It provides a recommendation ('event ... recommended for a specific market'), explains cross-event advantages, and even tells the agent when to use a sibling tool ('For custom sizing use polymarket_fill_risk').

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

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

The description adds substantial behavioral context beyond the read-only/idempotent/destructive annotations. It discloses detailed response segmentation (model_driven, structural_arbitrage, concentrated_longshot), the 24h-move warning, the fact that partition_overround returns kelly_fraction_half=0 at parent level by design, the caching behavior (1h at KV level keyed on all knobs), and the inclusion of diagnostics to explain empty segments. This goes far 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 long but well-organized, front-loaded with the core purpose, and each section (segments, knobs, response top-level, diagnostics, caching) earns its place. It is dense but not redundant. Slightly shorter phrasing could improve conciseness, but the complexity of the tool justifies the length.

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

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

With no output schema, the description carries the full burden of explaining return values. It specifies the top-level structure (by_segment, fed_candidates/fed_note, _diagnostics), the fields on every opportunity (edge_pp_net, kelly_fraction, market.liquidity, etc.), and the purpose of diagnostics for why segments are empty. This is comprehensive for a complex tool.

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

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

Even though schema coverage is 100%, the description adds meaningful cross-parameter semantics. It explains the role of 'Tradeable-Edge knobs' (min_liquidity, max_spread_pp) and clarifies that min_kelly never filters partition arbs because parent-level kelly_fraction_half is always 0, while min_partition_leg_kelly applies to per-leg Kelly instead. This interaction detail is not present in the schema and is critical for correct invocation.

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+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the purpose and distinguishes from siblings by mentioning 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets,' which sets it apart from other Polymarket tools.

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

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

The description provides clear context for when to use the tool ('Built for "what should I bet on today"') and explains the discovery advantage over manually paging markets. It also mentions that Fed bets are surfaced but excluded from ranking due to signal reliability, which is a usage caveat. However, it does not explicitly name alternatives or provide when-not-to-use guidance relative to sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

Annotations already declare readOnly/idempotent/non-destructive behavior, and the description adds valuable behavioral context: snapshots are written only on cache-miss (gaps mean no scan), history is bounded by a 60-day TTL, decay is computed on daily closes not intraday, and edge_pp_net is signed by trade direction. These details go well beyond the structured fields.

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

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

The description is well-structured into intro, Args, RESPONSE fields, and LIMITS. Every sentence earns its place, from explaining response semantics to noting the 60-day TTL. The first sentence front-loads the tool's purpose, and there is 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?

There is no output schema, yet the description fully documents return shapes (tracked[], expired[], snapshot_dates[]), field meanings, units, and edge cases (cache-miss gaps, TTL, decay limitations). Combined with complete parameter descriptions and informative annotations, an agent can select and invoke this tool with minimal inference.

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

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

Schema description coverage is 100%: both parameters have full descriptions with defaults and allowed values ('Lookback in days (default 14, clamp 2-30)' and '24hr | 1wk | 1mo (default 1wk)'). The description repeats similar info (days, window, defaults) without adding significant new meaning, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and directly answers 'how long has this edge existed and is it shrinking?' It clearly distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence/decay rather than current edge values.

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

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

It provides clear usage context: use for historical edge persistence and decay, with the warning that a fresh wide edge is a different trade from a 3-week-old one, and 'the median lifespan is your competition clock.' It does not explicitly name alternative tools or state when-not-to-use, but the intended context is unmistakable.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond these by detailing internal behavior: walking the order-book ladder, returning a verdict (clean|degraded|cannot_fill), computing per-leg fill detail, and identifying forced_directional_risk. It also warns about partial basket fills being the dominant loss mode, which annotations cannot convey.

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

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

The description is dense and well-organized with explicit mode labels (SINGLE-MARKET, BASKET) and front-loaded purpose. It is longer than average, but every sentence adds needed detail for a complex two-mode tool. Slightly verbose for quick scanning, but no wasted words.

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

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

For a tool with two modes, four params, no output schema, and no nested objects, the description fully compensates by enumerating all return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, etc.) and explaining the risk context. It also covers edge cases like partial fills and thin legs, making it complete for selection and invocation.

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

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

Schema coverage is 100%, but the description adds substantial semantic value: clarifies that market and event are mutually exclusive modes, explains the default and auto behavior for side, and reinterprets size_usd across modes ('max spend on buys, target proceeds on sells' vs 'settlement notional - shares per leg'). This far exceeds the schema descriptions.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which is a specific verb+resource combination. It clearly distinguishes two modes (single-market vs basket) and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by framing it as a pre-trade risk 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?

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial fills convert arb into unhedged directional risk), providing clear context and alternatives.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses the matching algorithm (token-overlap), the meaning of skipped_cross_type/subtype, temporal alignment checks, and the important caveat that most macro shortcuts currently return compatibility warnings. This adds substantial behavioral context that annotations cannot convey.

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

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

The description is packed with essential information, structured by TWO MODES, RESPONSE, SAFETY FIELDS, and a closing caution. It is dense but every sentence adds value; however, the long paragraph format could benefit from bullet points or clearer separation of sections for easier scanning.

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 the response structure including leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped_cross counters. It also covers edge cases (non-equivalent bet shapes, unrelated events) and the current state of pre-mapped topics, making the tool's behavior fully 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?

While the schema already documents each parameter, the description enriches them by explaining the two modes: 'topic' auto-fetches matching events, while explicit ticker/slug parameters override the mapped sides. It also clarifies that the topic parameter accepts specific shortcuts, adding interactive semantics beyond mere type 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 opens with a specific resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly identifies the tool's function and scope, and the mention of two venues distinguishes it from sibling tools like polymarket_arbitrage (which likely operates within a single venue or different context).

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

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

The description explains when to use the tool ('when the bet shapes are equivalent that delta is a real signal') and when results are unreliable (compatibility_warning cases). It also details two modes (topic shortcuts vs explicit tickers) and warns that pre-mapped topics are often not tradeable, providing clear guidance on expected outcomes.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: the scoping mechanism (anonymous IP, BYO key hash, account ID) and the dual retrieve/list behavior. It does not mention error scenarios, but the added context is meaningful.

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

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

The description is three sentences, front-loaded with the main action. It includes examples and scoping info, each sentence earning its place. It is slightly more verbose than strictly necessary but remains efficient and structured.

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

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

The tool is simple with one optional parameter and no output schema. The description covers purpose, usage scenarios, scoping, and relationship to siblings. It does not describe the return format, but for a simple retrieval tool this is acceptable and the description is otherwise 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% — the schema already says 'Memory key to retrieve (omit to list all keys)'. The description reiterates this behavior but adds no new parameter-level detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a value previously saved via remember or lists all saved keys when the key argument is omitted. It includes concrete examples of use cases and distinguishes itself from related siblings (remember and forget) by explicitly pairing with them.

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

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

Provides explicit usage context: use it to look up previously stored context (target ticker, address, research notes) without re-deriving it. It also clarifies how to invoke the list behavior (omit the key) and notes scoping to the caller's identifier, which helps determine when to use this tool.

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

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

Even though annotations mark readOnlyHint=true, the description transparently discloses that mark_read:true flags events as read, affecting subsequent calls. It also explains the persisted feed and open-world behavior (next call only shows newer ones), adding valuable context 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?

The description is three sentences, front-loaded with the primary action. Every sentence provides useful information—purpose, output details, filtering options, mark_read side effect, and alternative access—with no fluff or repetition.

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

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

Given 5 optional parameters, no output schema, and read-only annotations, the description is remarkably complete. It covers filtering, limit default (in schema), mark_read side effects, event fields, polling suitability, and an alternative HTTP endpoint, leaving no critical gaps for an agent to misuse the tool.

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

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

Schema coverage is 100% (all 5 parameters documented), so baseline is 3. The description adds value by giving an example type ('sec_8k'), explaining the effect of mark_read on future calls, and describing the returned event fields (source, citation_uri, raw payload), which goes beyond schema descriptions.

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

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

The description opens with 'Pull fired events from your subscription feed', a specific verb+resource. It further explains that each alert carries source, citation_uri, and raw payload, and distinguishes itself from sibling tools like list_subscriptions by focusing on events rather than subscription management.

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

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

The description gives clear usage context: filtering by type and since, setting mark_read, and polling. It also points to an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts and dashboards. It doesn't explicitly enumerate sibling alternatives, but the context is unambiguous and practical.

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), the description details the data sources (SEC EDGAR, GDELT→GNews fallback, USPTO), the fallback mechanism, and the PatentsView sunset soft-fail. It also discloses the return structure (changes[] grouped by source, total_changes, citation URIs). This is rich behavioral context.

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

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

The description is compact yet dense, front-loaded with query examples, then source mechanics, parameter syntax, and return format. Every clause adds value, and the alternative tool mention is placed at the end for emphasis.

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 feed tool with no output schema, the description covers usage, sources, fallback behavior, parameter syntax, return structure, and an alternative. It is sufficiently complete for an agent to invoke correctly without additional context.

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

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

The schema already covers all parameters fully, but the description adds practical semantics: 'since' accepts ISO dates or relative shorthand with examples, and 'value' is exemplified with a ticker and CIK. It also notes 'type' only supports 'company' today.

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 change feed for a company over a date window, with specific verbs like "what's new" and "updates on". It distinguishes from sibling tool entity_profile by explicitly noting that tool for static profiles.

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 example queries ('What's new with X', 'updates on Acme') and a clear alternative rule: 'Use entity_profile instead when you want the static profile...'. This gives the agent concrete guidance on when to choose this tool over a sibling.

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

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

The description adds meaningful behavioral context beyond the annotations: persistence differences for authenticated vs. anonymous sessions, 24-hour retention, and identifier scoping. This enriches the safety profile provided by annotations without any contradiction.

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

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

Four sentences, front-loaded with the core action, then usage context, then technical details. Every sentence earns its place; no redundancy or 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?

Covers when (discovery of reusable info), why (avoid re-lookup), how (key-value pair, scoping, persistence), and related tools (recall/forget). For a simple store tool, this is complete; no output schema needed for a write operation, and the description is 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 descriptions for key and value, but the description adds value by explaining the key-value nature and scoping ('Stored as a key-value pair scoped by your identifier'), and provides examples in the usage section that clarify param semantics.

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

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

The description clearly states a specific action ('Save data the agent will need to reuse later') and explains the resource (key-value memory scoped by identifier). It distinguishes from siblings by pairing with recall and forget, making the purpose unambiguous.

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

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

Explicitly states when to use: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference). Also mentions pairing with recall and forget as complementary alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-destructive lookup. The description adds value by detailing the cascading internal architecture ('each call cascades through several lookup endpoints internally') and the fallback behavior. However, it does not clarify whether the tool is stateful beyond idempotence or whether there are rate limits given the multiple internal lookups. With strong annotations, a 3 is appropriate.

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

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

The description is information-dense but front-loaded with examples and the primary directive. Every sentence adds unique value: intent examples, usage guidance, type-specific resolution details, and behavior notes. Some redundancy exists (e.g., mentioning ticker multiple times), and the length could be trimmed slightly, but overall it is well-organized and avoids 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?

Given the two-parameter schema (100% coverage) and no output schema, the description thoroughly covers the tool's capabilities. It explains the resolution process for company types (SEC EDGAR, GLEIF, OpenFIGI), drug types (RxNorm), and the cascading internal logic. The only missing detail is a brief note on the expected output format or structure, but with annotations covering idempotence and safety, the description is sufficiently complete for an agent to use the tool effectively.

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 well-described parameters for type (enum of company/drug) and value (detailed string format per type). The description adds significant context beyond the schema by explaining that an ISIN input resolves to the legal entity via GLEIF mapping and that LEI/FIGI enrichment degrades gracefully. This elaboration of the actual resolution process is valuable for understanding edge cases and input formatting.

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

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

The description states a clear purpose with specific verbs and noun phrases: 'resolve a user-spoken NAME to the canonical/official identifiers' and includes comprehensive examples of user intent. It explicitly differentiates between resolving 'company' and 'drug' types, each with a distinct identity spine (CIK/ticker/LEI/FIGI for company, RxCUI for drug). This high specificity helps the agent distinguish it from siblings like 'compare_entities' or 'entity_profile'.

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

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

The description provides explicit guidance on when to use this tool: 'Use FIRST whenever you have a name but need an ID.' It also specifies what inputs are acceptable for company (ticker, CIK, ISIN, or company name) and describes the graceful degradation behavior when external sources are unavailable. This clear directive prevents misuse and clarifies when alternatives would be unnecessary.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so description focuses on process: probes entities with ai_visibility_check, ranks by score, surfaces most/least recognized. It also discloses return fields (score, confidence, signal density). No contradiction with annotations. Could add rate-limit or performance context, but acceptable.

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

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

Three sentences, strategically front-loaded: first sentence states the action, second explains the mechanism, third gives the use case and output. Every sentence earns its place; no fluff or repetition of schema details.

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 adequately covers return values (ranked list with score, confidence, signal density). It explains the tool's purpose, usage context, and input constraints (2-8 entities, first is subject). Could mention error behavior or time cost for N probes, but not critical for a read-only comparison tool.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces the 'first entry is subject' rule and the purpose of entities, but adds no new parameter meaning beyond the schema. It does not introduce undocumented constraints or clarify the models array beyond what's already in the schema.

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

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

The description uses a specific verb ('Compare') and resource ('AI presence across multiple entities'), clearly distinguishing it from sibling tools like ai_visibility_check (single-entity) and compare_entities (generic comparison). It explicitly states the output (ranked list with score, confidence, signal density) and the 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?

Provides a concrete use case ('competitive AI-marketing audits') and example question ('does Claude know about us as well as our competitors?'). It implicitly contrasts with ai_visibility_check by stating it probes each entity side-by-side. Lacks explicit 'when not to use' or alternatives, but the context is clear.

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

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

Surpasses the annotations by adding context: fans out to multiple external sources, bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully, and sources_failed lists timed-out sources. The description details latency, failure handling, and what continues to return, which is material additional context beyond the readOnly/idempotent hints.

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

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

The description is dense but front-loaded: it starts with the purpose, then when-to-use, then outputs, then limitations. Every sentence carries important information, and the structure is logical. It's longer than typical but justified by the tool's complexity, avoiding any fluff.

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

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

Despite no output schema, the description explains the return format (summary fields, advisories, links, alternatives), failure behavior, latency caveats, and ecosystem limitations. For a multi-source composite tool with edge cases, this is a complete and useful description that enables correct invocation and interpretation.

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

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

Schema description coverage is 100%, so the schema already documents package and version parameters. The description adds little beyond what the schema provides (e.g., it doesn't explicitly mention that package is a name or version defaults to latest beyond the schema). It does mention scope acceptance indirectly, but that is already in the schema. Therefore, baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose as a composite 'should I add this npm package' check, naming the specific actions (scans deps.dev and bundlephobia) and the output (summary block, advisories, links). This distinguishes it from sibling tools and gives a specific verb+resource with concrete 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?

Explicit guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states exclusions (NPM only, other ecosystems fall under deps.dev directly) and behavior on partial failures (sources_failed lists timeouts). This gives clear when/when-not guidance and alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds valuable behavioral context: it returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char windows, and truncates inputs over 200K chars with a flag. This goes well beyond the annotation safety profile and sets accurate expectations for outputs and limits.

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: a one-sentence core purpose, followed by usage guidance and then technical details. Every sentence earns its place—no repetition or filler. It front-loads the key verb and resource, making it scannable.

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

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

For a tool with 3 parameters, full schema coverage, and no output schema, the description covers the essentials: inputs, output characteristics (top-N passages with offsets/scores), algorithm, constraints, and relationship to a sibling tool. It also includes a practical cap and truncation behavior, making it actionable for an AI agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances parameter meaning by showing concrete examples ('SEC 10-K body, an article, a long tool result', 'supply-chain risk') and clarifying that text is the already-pulled content and query is a natural-language request. This adds context beyond the schema's field descriptions, 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 opens with 'Semantic search INSIDE a fetched record,' which clearly identifies a specific verb (search), resource (fetched record), and scope (inside rather than across records). It distinguishes from sibling tools like ask_pipeworx_grounded by explaining that search_within operates on text already pulled, not on the broader knowledge base.

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

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

It provides explicit usage guidance: 'Use when the record is too big to cram into the prompt' and 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This tells the agent exactly when to use it and how it fits with an alternative tool.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, etc.), the description discloses important behavioral details: account requirement, return value, SMS verification and daily cap, webhook signing secret returned once, and auto-disable after 10 consecutive failures. These add meaningful context and do not contradict 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 dense yet well-organized. It front-loads the core purpose, then methodically covers types and delivery channels. Every sentence contributes useful information; there is no filler or redundancy.

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

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

Given the tool's complexity (3 parameters, nested objects, 5 enum types, delivery options), the description covers the primary use cases, account requirements, and output. Some type-specific details are only in the schema, but the description provides enough context to operate effectively. It also mentions the always-on feed and how to pull alerts.

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, including detailed type-specific examples in the 'params' description. The tool description adds a few brief examples but does not significantly enhance what the schema already states. Baseline 3 is appropriate since the schema carries the semantic weight.

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

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

The description clearly states that this tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. This distinguishes it from siblings like list_subscriptions, unsubscribe, and recent_alerts, which manage or read alerts rather than create them.

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 prerequisites (requires Pipeworx OAuth account, anonymous/BYO cannot persist subscriptions) and explains each supported type with examples. It also covers delivery channels and constraints, giving clear context for when to use this tool. It does not explicitly name alternative tools but the context is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond annotations: it returns category-bucketed example questions with exact tool and argument shapes, and supports optional topic focusing. This gives a full picture of the tool's behavior without contradicting the safety profile.

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

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

The description is lengthy but each sentence serves a purpose: it lists example user intents, explains the return format, describes the topic parameter, and gives usage guidance. It is well-structured and front-loaded with the most important context, though a slight trimming of the query examples at the start could improve 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 tool with no output schema, the description sufficiently explains the return value (category-bucketed example questions with tool/argument shapes) and covers both invocation modes (no args vs. topic). It also situates the tool within the broader tool catalog, making it fully contextualized 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?

The input schema covers the optional `topic` parameter with description and allowed examples. The description reinforces this by listing example values (finance, pharma, betting) and explaining that omitting it yields a cross-category spread. This adds slight value over the schema, justifying a score above the baseline of 3.

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

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

The description clearly identifies the tool as the onboarding entry point for connecting to Pipeworx, with a specific purpose: returning category-bucketed example questions. It distinguishes from siblings by explicitly naming meta-tools like ask_pipeworx and entity_profile, and positioning itself as the first tool to use for exploration.

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

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

Explicit guidance is given: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. This provides clear when-to-use direction and names alternatives, leaving no ambiguity about its role versus sibling tools.

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

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

Adds valuable behavioral context beyond annotations: ownership enforcement and the deactivation vs deletion distinction. This aligns with destructiveHint: false and idempotentHint: true, and does not contradict any annotations.

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

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

The description is two sentences, front-loaded with the main action, and every sentence adds meaningful detail without redundancy.

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

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

For a simple one-parameter tool with strong annotations and schema, this description covers the action, constraints, effect, and alternative path. No output schema exists, so return values aren't expected to be explained.

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 single parameter 'id' with its type and origin (returned by subscribe). The description adds no additional parameter-level meaning, so the baseline score of 3 applies.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific resource. It distinguishes from siblings by mentioning ownership enforcement and deactivation, which is distinct from subscribe, list_subscriptions, and recent_alerts.

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

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

Provides clear context about when it applies (only your own subscriptions) and points to an alternative for historical events (recent_alerts). It doesn't explicitly mention list_subscriptions for viewing active subscriptions, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context beyond this: it explains the return verdicts, the special meaning of could_not_verify (including the verification_error field), the distinction between could_not_verify and unsupported, and the fast-path vs grounded pipeline routing. This is exactly the type of behavior disclosure that helps an agent use the tool appropriately.

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 detailed but well-structured, front-loaded with trigger phrases and use-case, then proceeding to routing logic, return values, and edge-case clarifications. It is longer than the ideal but every sentence conveys essential information without redundancy, so the verbosity is justified. No filler content.

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

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

With no output schema, the description fully covers what the tool returns: the verdict list, the grounded/structured value with citation, and reasoning. It also addresses error conditions and how to interpret them, including the distinction between 'could not verify' and 'unsupported'. This makes the tool's behavior completely understandable in context, even without an output schema.

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

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

Though schema coverage is 100%, the description adds critical semantics beyond the schema. It explains that tolerance_pct overrides the tolerance implied by the claim wording, recommends specific values for hallucination detection, and notes the default cap. It also gives concrete examples for the claim parameter, making parameter usage far more intuitive than the bare schema descriptions.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with concrete trigger phrases. It differentiates from siblings by specifying the exact use case (fact-checking) and the distinction between company-financial claims (via SEC EDGAR fast path) and other claims (grounded pipeline), making its scope unambiguous.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides guidance on when to use it versus alternatives by noting it replaces 4–6 sequential calls. It also gives specific parameter advice (setting tolerance_pct for hallucination detection) and clarifies the meaning of could_not_verify vs unsupported, which is essential for correct invocation and interpretation.

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