Macvendors

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true. The description adds behavioral details: default model is free, probing Anthropic requires the user's own API key and direct payment, and the output includes per-model scores and raw responses. It does not mention rate limits or latency, but the annotations cover safety.

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 primary purpose. Every sentence adds value: core functionality, optional cost note, and return structure. No filler 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 the tool has 4 parameters, no output schema, and rich annotations, the description covers inputs well and mentions the return structure (per-model {score, confidence, signals, raw_response} + combined view). It does not explain the combined view in detail, but is sufficient for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful context: explains that 'entity' can be a brand, product, etc.; 'models' lists supported values; '_apiKey' clarifies pass-through billing; and 'context' helps disambiguate. This goes beyond the schema's minimal 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 specifies a clear verb ('probe'), resource ('LLMs'), and scope ('score visibility 0-100 per model'). It distinguishes itself from siblings like 'ask_pipeworx' by focusing on AI visibility auditing rather than general Q&A or research.

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

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

The description states it is 'useful for AI-marketing audits, pre-launch brand checks, competitive monitoring,' providing clear use contexts. However, it does not explicitly exclude scenarios or compare to sibling tools like 'scan_competitor_ai_presence', so it lacks explicit when-not-to-use guidance.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior, and the description adds valuable context: it routes to sub-tools, returns citations, works on every tier, and is a single fast call. It does not discuss error cases or rate limits, but the behavioral disclosure is strong and consistent 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?

While longer than typical descriptions, every sentence earns its place: the opening 'PREFER OVER WEB SEARCH' is a strong front-loaded directive, followed by concrete examples, routing behavior, and explicit upgrade paths. The structure is logical and there is no redundancy.

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

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

Given the tool's high complexity, the description covers when to use it, what inputs look like, what kinds of questions it handles, how it behaves (routing, citations), and when to choose alternatives. It is fully self-contained for an agent to select and invoke correctly, 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?

Schema coverage is 100%, with all six parameters (question and its five aliases) described in the input schema. The description adds example questions and states 'Your question or request in natural language', but it does not substantially enhance parameter-level meaning beyond what the schema already provides, so the baseline 3 applies.

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

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

The description clearly states that the tool routes questions to one of 5,529 tools across verified sources and returns a structured answer with pipeworx:// citation URIs. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives, making its purpose specific and unique.

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

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

The description gives explicit when-to-use guidance, instructing agents to 'PREFER OVER WEB SEARCH' for a wide range of factual queries and to 'START HERE for most questions'. It also provides clear exclusions and alternatives: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions, plus specific handling for breaking news.

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 candidate routing improvements are enabled live under test, that currently no candidate is active (last retired 2026-07-26), and that it fully falls back to being a working router. This adds dynamic behavioral context beyond the annotations' 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?

Four sentences, front-loaded with 'Beta version of ask_pipeworx,' and each sentence delivers essential information: core identity, current state, usage guidance, and fallback behavior. No fluff or redundancy.

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

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

For a complex experimental router, the description covers what it is, how it relates to the stable version, when to use it, and what to expect (same response shape). With no output schema, mentioning the identical response shape is crucial and complete.

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

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

The input schema provides 100% coverage with all six parameters (question and five aliases) fully described. The description adds no extra parameter meaning, so it leverages the schema's baseline without needing to compensate.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes itself as the experimental edge with candidate routing improvements, differentiating it from sibling ask_pipeworx and other tools.

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

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

Explicitly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing,' and explains that results are compared against the stable router to decide merges. This provides clear context on when to use the beta versus the stable version, even mentioning the current no-active-candidate state.

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

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

Despite having annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds significant behavioral context: it explains the routing and extraction process, the exact success/refusal return shapes with refusal_reason enums, and the guarantee of using 'ONLY what the tool result contains.' This goes well beyond the annotations.

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

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

The description is dense and well-structured, front-loading the core purpose and then layering return format, use cases, and cost trade-off. It is slightly verbose in explaining the routing process, but every sentence adds value. Minor excess length prevents a perfect score.

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

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

For a tool with no output schema, the description thoroughly covers return values, refusal reasons, and use-case applicability. It also explains the relationship to sibling tools and the cost implication, making it fully self-contained for an agent to decide 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 coverage is 100% and the only parameter is 'question' with aliases clearly documented in the schema. The description does not add new parameter semantics beyond what the schema already provides. Baseline 3 is appropriate since the schema handles the heavy lifting.

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

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

The description clearly identifies a specific, distinct mode: 'Hallucination-resistant answer mode for high-stakes reads.' It specifies the verb ('EXTRACTS the answer') and resource (tool results from routing). It explicitly differentiates from sibling 'ask_pipeworx' by describing the grounded extraction and refusal behavior.

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

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

Provides explicit when-to-use guidance ('whenever an answer will be quoted, cited, or acted on') and when-not-to ('prefer ask_pipeworx for casual lookups'). It also names the sibling tool directly and mentions the cost trade-off ('Costs one extra LLM call'), giving clear decision criteria.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral details: fan-out logic, response shapes with specific fields, resolver contract (confidence, alternatives, suggestions), parent event extraction, news fallback handling, safety mechanisms for low-confidence/closed markets, wide-spread liquidity notes, and resolution-rule risk. 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 front-loaded with the main purpose and input flexibility. It uses clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) for easy scanning. While lengthy, every sentence adds context for a complex tool with many special cases. Could be slightly trimmed, but the structure earns a 4.

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

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

Despite no output schema, the description covers all key response fields (result.market, result.analysis, result.evidence, result.market_match_confidence, result.parent_event, news fields, etc.) and explains behavior for numerous edge cases (low-confidence, closed markets, wide spreads, resolution rules). Given 3 parameters and no output schema, this is remarkably complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds significant value: explains that 'market' accepts slug, URL, or question text; defines 'depth' enum values ('quick' = 2-3 sources, 'thorough' = full fan-out); describes 'include_raw' purpose and when to use true/false. This goes well beyond the schema's property 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 begins with a clear verb+resource ('Research a Polymarket bet') and specifies the input types (slug, URL, question text). It outlines the full pipeline (resolves, classifies, fans out, returns evidence packet + comparison). The sibling tools (e.g., polymarket_edges, polymarket_arbitrage) are distinct in scope, and the description naturally differentiates by covering the complete research flow.

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 use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides extensive guidance on when to inspect certain fields (e.g., market_match_confidence, parent_event, resolution-rule risk) and what to check before trusting results. It also warns about low-confidence matches and closed markets, effectively telling the agent when not to act.

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

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

Annotations already indicate read-only, idempotent, and open-world. The description adds rich behavioral context: it fetches latest SEC data for companies with correct fiscal year handling, pulls FAERS and FDA data for drugs, sorts results by primary metric, and returns citation URIs. No contradiction with annotations.

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

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

The description is well-structured, starting with common queries and then detailing behavior per type. Every sentence adds value, but it is slightly verbose (e.g., listing multiple example queries could be condensed). Overall, it earns its length without excess.

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 2 parameters and no output schema, the description thoroughly covers input usage, per-type behavior, output format (sorted results, citation URIs), and when to prefer it over other tools (replaces 8-15 sequential lookups). No gaps for an AI agent to misunderstand.

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 significant meaning: it explains that 'type=company' pulls revenue, net income, cash, debt from SEC, and 'type=drug' pulls adverse event counts, FDA approvals, trial counts. For 'values', it clarifies format per type (tickers/CIKs vs. drug names) and repeats min/max constraints. This far exceeds the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It uses explicit verbs like 'compare', 'rank', and specifies the resources ('companies', 'drugs'). It distinguishes from siblings like 'lookup' by emphasizing parallel retrieval over sequential lookups.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists trigger phrases like 'compare X and Y' and 'X vs Y'. It also clarifies when to use each type ('company' for financials, 'drug' for pharma data) and implies exclusivity (not for single entity queries).

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description goes well beyond these by explaining output structure (findings packet with verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citations), explicit gaps[] for unanswered facets, contradictions[] for disagreeing findings, hop field, semantic excerpting of large records, and time expectations (15-60s, thorough up to ~90s). No contradiction exists.

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

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

Though long, the description is densely packed with essential information and well-structured. It opens with the critical account requirement, then explains core functionality, use cases, exclusions, depth semantics, citation behavior, and performance expectations. Every sentence contributes value, and front-loading is effective.

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

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

With no output schema, the description carries full burden for explaining return values, which it does thoroughly: findings packet, gaps[], contradictions[], hop field, citation_uri, and semantic excerpting. It also covers auth requirements, timing, depth options, and exclusions. The tool is complex (2 params, depth enum, parallel execution) and the description fully addresses all context needed for an agent to invoke and interpret results.

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

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

Schema covers 100% of parameters with detailed descriptions, so baseline is 3. The description adds interpretive context beyond the schema: explaining how depth affects facet count, gap recovery, and contradiction scanning with practical examples like 're-angles unanswered facets'. This elevates it slightly above baseline, though the schema already covers the technical details.

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 core purpose: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, explicitly distinguishing it from open-web search. It names specific resources (SEC filings, FRED/BLS, FDA, USPTO) and uses a specific verb ('research'). It also differentiates from sibling ask_pipeworx by scope and call-structure.

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

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

The description provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and when-not-to-use: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also mentions account requirements and fallback behavior (use ask_pipeworx if not signed in), covering exclusions and alternatives thoroughly.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context by stating the tool returns full input schemas with curated examples ready to call, and that it is a discovery tool. No contradictions.

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

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

The description is well-structured with a clear front-loaded purpose, followed by examples and output details. It is slightly long but every sentence adds value; 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?

Given the tool's complexity and 100% schema coverage, the description adequately explains what it returns (names, descriptions, schemas with examples). It does not specify return format details like pagination, but for a discovery tool this 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 all six parameters described. The description clarifies that multiple parameters (task, q, description, search) are aliases for query, which adds meaning beyond the schema. It also provides natural language examples in the text.

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 finds tools by describing data or task, enumerates many example use cases, and specifies the output returns top-N relevant tools with full schemas. This distinguishes it from sibling tools like deep_research or entity_profile which are more specialized.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use it for initial exploration, and the context of having many tools implies when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields, and notes the USPTO API sunset. It also discloses that it makes 'ONE parallel call', which is not in annotations.

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

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

The description is front-loaded with purpose and examples, then provides usage preference, then details returns. Every sentence adds useful information without redundancy. Despite length, it is efficiently 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?

No output schema exists, so the description fully covers return fields: CIK, company_name, recent_filings (with URI format), fundamentals (Revenues, NetIncomeLoss, Cash), patents, news, and LEI. It also notes limitations (no names, USPTO sunset). This is complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by reiterating that value can be ticker or zero-padded CIK, and gives examples ('AAPL', '0000320193'). It also explains the 'type' parameter's current limitation to 'company'. This goes beyond the schema alone.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company' and lists concrete example user prompts (e.g., 'Tell me about X', 'research Acme'). It distinguishes from siblings by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and from similar tools like 'compare_entities' or 'deep_research' by focusing on a single entity.

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

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

Explicitly says when to use: 'when the user asks for a holistic view' and 'ALWAYS PREFER over chaining...'. Also states when not to use: 'Names not supported — use resolve_entity first if you only have a name', providing a clear alternative.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about why to delete (stale data, task done, sensitive data) but does not elaborate on irreversibility or side effects beyond the annotation.

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 key information. 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?

Given the tool's simplicity (one required parameter, no output schema), the description fully covers purpose, usage, and relationships with siblings.

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 'key' parameter is described as 'Memory key to delete'. The description mentions 'by key' but adds no new meaning beyond the schema.

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

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

The description clearly states the action ('Delete') and resource ('previously stored memory by key'). It mentions pairing with 'remember' and 'recall', which suggests complementary functionality but does not explicitly differentiate from siblings.

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

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

Provides explicit usage conditions: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with siblings, but no exclusions or when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds behavioral details: fetches the page, extracts title/description/key links, and emits standard markdown. It does not contradict annotations and provides context beyond them.

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

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

The description is three sentences, each earning its place: what it does, how it works, and use cases. No fluff, front-loaded with purpose.

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

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

For a simple tool with robust annotations and complete schema, the description covers the output format ('single text blob ready to drop at site-root/llms.txt') and use cases adequately. No output schema needed.

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

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

Schema coverage is 100% with clear descriptions for both parameters (url, max_links). The description adds no additional 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 verb 'generate', the resource 'llms.txt file', and the scope 'for any URL'. It distinguishes from sibling tools by specifying the unique output format and use cases like indexing a client's site or auditing a competitor.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It implicitly suggests when not to use (other indexing tasks), but lacks an explicit exclusion statement.

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

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

Annotations already mark as readOnly and idempotent. Description adds which fields are returned and clarifies 'active' vs 'inactive' via parameter hint. No contradictions.

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

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

Two sentences front-loading purpose, then returns, then usage. No redundant 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?

For a simple tool with one optional param and no output schema, description covers purpose, return fields, and usage context completely.

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 parameter with 100% description. Description reinforces relation to 'active' vs 'cancelled' but doesn't add new semantic meaning 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?

Clearly states 'List the caller's active subscriptions' with specific verb and resource, and lists returned fields. Distinguishes from siblings like 'subscribe' and 'unsubscribe'.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear when-to-use and implied when-not-to.

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

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

Annotations already mark it as read-only, open-world, idempotent, and non-destructive. The description adds key behavioral details: keyless access and rate limit (~1 req/s). 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?

Two sentences, front-loaded with purpose, no extraneous words. Efficient and easy to parse.

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

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

Given one parameter and no output schema, the description covers purpose, input format, rate limit, and keyless access. It does not describe response format, but for a simple lookup this is likely 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 a clear description of the 'mac' parameter accepting various formats. The description reinforces that full MAC or first 6 hex digits work, but adds no new meaning beyond the schema.

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

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

The description clearly states the tool's purpose: MAC address to hardware manufacturer lookup via macvendors.com. It specifies the input (full MAC or first 6 hex digits) and output (manufacturer/OUI). Among sibling tools, none overlap, so there is clear distinction.

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 (MAC address lookup) and mentions it's keyless and rate-limited. While it doesn't explicitly list alternatives or when not to use, the context is sufficient given no similar sibling tools exist.

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

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

Annotations provide only basic hints (readOnly=false, destructive=false), but the description goes further, disclosing that filing without an account returns a claim_token for later status checks, that the team reads digests daily, and that the tool is rate-limited to 5 per identifier per day. These behaviors are not inferable from annotations, so the description adds valuable 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 longer than average but every sentence contributes: purpose, usage triggers, exclusion criteria, token mechanics, and rate limits. It's logically ordered and front-loaded with the primary purpose. While slightly verbose, it remains efficient and readable.

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

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

The description addresses key aspects the agent needs to know: what to report, when to use it, how the claim_token flows, and operational constraints (rate limit, free usage, daily digestion). It doesn't describe the response format, but the claim_token mention partially covers that. Given the tool is a simple feedback channel, the description is sufficiently complete.

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

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

The input schema already includes descriptions for all 4 parameters (100% coverage), but the tool description adds crucial usage semantics: it explains how to use claim_token to read previous reports, instructs users to describe issues in terms of Pipeworx tools/packs rather than pasting user prompts, and clarifies the 'type' values with real-world examples. This goes beyond the schema's generic 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 phrase 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly identifying the tool's purpose as reporting feedback about Pipeworx tools. It further differentiates from sibling tools like ask_pipeworx or discover_tools by explaining it's exclusively for issues with this connection's own tools, not for data queries.

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

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

The description provides explicit when-to-use conditions: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and advises filing with other servers for different vendors. This is exemplary guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This discloses source, privacy, and caching behavior beyond what annotations provide.

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

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

The description is concise, front-loaded with the main purpose, and uses bullet points for use cases. Every sentence adds value 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?

The description covers purpose, usage guidelines, behavioral traits, and output details sufficiently for a simple one-parameter read tool. While no output schema exists, the description specifies returns ('top tools, top packs, and total call volume'), which is adequate.

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 only parameter is 'window' with an enum. The input schema already fully describes it ('24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand.'). Since schema coverage is 100%, the description adds no extra meaning, meeting the baseline.

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

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

The description clearly states the tool returns trending data: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb and resource, and distinguishes itself from siblings like discover_tools by focusing on current usage trends.

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

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

The description provides three explicit use cases and gives guidance on window selection ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). However, it does not explicitly state when not to use the tool or mention alternative tools for different needs.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds substantial behavioral context: default scan scope (top 200 markets), semantic anchor (Jaccard similarity >=0.30), partition filter (placeholder slugs), fill check against CLOB depth, and realizable edge threshold. No contradiction.

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

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

Well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded main functionality. However, it is verbose and contains some redundant phrasing that could be trimmed 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?

Very thorough despite no output schema. Describes response format (opportunities[] with fields, partition_check in event mode), default behavior, edge case handling (placeholders, similarity), and fill check conditions. Covers all essential aspects for an agent to use the tool correctly.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning beyond schema: explains event accepts full URLs, topic is a seed question, and describes the scanning behavior for each. This elevates value above baseline.

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

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

The description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks, with two distinct modes (event and topic). It does not explicitly differentiate from sibling tools like polymarket_edges, but the purpose is specific enough.

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

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

Provides explicit guidance on when to use each mode: no args for trending scan, event for single-event partition check, topic for cross-event scan. Includes fill check warning on when not to trade. Lacks explicit when-not-to-use overall, but recommendations are 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds extensive behavioral context: caching details (cached 1h at KV level keyed on all knobs), computation details for each model family, edge calculation methodology, Kelly sizing, slippage assumptions, and diagnostics for empty segments. 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 very long and dense, packed with technical details. It front-loads the purpose but then dives into intricate model formulas. While every sentence adds value, it could be more structured (e.g., bullet points or sections) to improve readability for an AI agent.

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

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

Given the complexity (9 parameters, three segments, caching, diagnostics), the description is exceptionally complete. It explains the response structure (by_segment, fed_candidates, _diagnostics) despite no output schema, and covers all filtering knobs with trade rationale. No gaps remain for an agent to use 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 descriptions for all 9 parameters. The description adds deeper context beyond the schema, such as explaining why min_kelly doesn't filter partition arbs (min_partition_leg_kelly applies instead), and providing rationale for default values like slippage_pp. This adds meaningful insight.

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 scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price. It distinguishes from siblings by emphasizing the 'edges' concept and the three specific segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), making its purpose specific and unique.

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 it's built for 'what should I bet on today' and helps agents discover opportunities without paging through hundreds of markets. It provides knobs for filtering and tradeability. However, it does not explicitly state when not to use this tool vs. alternatives like polymarket_arbitrage, but the context is clear enough.

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

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

Annotations indicate readOnly, openWorld, idempotent. The description adds significant behavioral context: response structure (tracked, expired, snapshot_dates), field meanings (signed value, decay computed on absolute), limitations (60-day TTL, daily closes not intraday), and data source conditions.

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

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

A single dense paragraph covering all essential aspects. Every sentence adds value, though a slightly more structured format (e.g., separating response fields) could improve readability. No superfluous text.

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

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

No output schema, but description fully documents response fields and their meanings. Covers parameters, limitations, data source behavior, and usage context. Complete for a read-only analytics 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 covers both parameters, but description adds useful specifics: default values, clamp range for days, and explains window as 'snapshot family'. This adds meaning beyond the schema.

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

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

The description explicitly states the tool's purpose: edge persistence and decay telemetry. It answers 'how long has this edge existed and is it shrinking?' and distinguishes it from sibling tool polymarket_edges by focusing on historical time-series and trend analysis.

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 guidance on when to use: comparing fresh vs. old edges. Implicitly contrasts with polymarket_edges (raw edges). Includes example scenario to illustrate the tool's value.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds significant value by explaining the output structure, the ladder-walking process, and critical risks like unhedged directional positions from partial fills, which goes beyond annotation information.

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

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

The description is long but well-structured with clear sections, a front-loaded summary, and every sentence adds value. It could be slightly more concise in the basket description, but overall it is efficiently 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?

Given no output schema, the description thoroughly explains all return fields for both modes, including edge cases like thin legs and forced directional risk. It covers the complex dual-mode behavior and warns about the dominant loss mode, making it complete for such a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context such as auto-detection of side for basket mode, interpretation of size_usd as settlement notional for baskets, and clamping bounds. This provides meaningful additional 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 'Realizable-vs-theoretical edge check against live CLOB order-book depth' with specific verbs and resource distinction between single-market and basket modes. It explicitly differentiates from siblings like polymarket_arbitrage and polymarket_edges by indicating when to use this tool.

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

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

The description provides explicit directives: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains the risks of partial basket fills and the consequences of not using this tool, giving clear guidance on when and why 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: two modes, compatibility_warning conditions, temporal alignment field, skipped_cross counters. 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 long but every sentence contributes value. It is front-loaded with core concept, then modes, response fields, and safety fields. While slightly verbose, it remains well-structured and efficient for the complexity.

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

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

Given the tool's complexity (cross-venue, multiple modes, safety warnings) and the absence of an output schema, the description compensates by detailing response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It provides complete context for understanding tool behavior and output.

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

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

Schema coverage is 100% for 3 parameters. The description adds meaning beyond the schema: enumerates topic options, explains override behavior for kalshi_event_ticker and polymarket_event_slug, and provides examples. Each parameter's role is thoroughly clarified.

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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, using explicit verb 'cross-venue spread' and resource. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparison.

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

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

The description explicitly details two modes (topic and explicit) with examples, and warns that most pre-mapped topics return compatibility_warning. It provides clear context on when spreads are meaningful (equivalent bet shapes, temporal alignment). However, it does not explicitly contrast with sibling tools or state when not to use this tool.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral context like scope and list behavior, but could detail return format.

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 main action, 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?

With one optional parameter, annotations covering safety, and no output schema, the description provides sufficient context for an agent to use the tool correctly.

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

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

Schema covers 100% of parameter. Description explains dual behavior (retrieve vs list all keys) based on key presence, which adds meaning 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?

The description clearly states the tool retrieves a value saved via 'remember' or lists all keys, distinguishing it from sibling tools like 'remember' and 'forget'.

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

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

Explicitly specifies when to use (look up stored context without re-deriving), how it pairs with remember/forget, and that it is scoped to an identifier.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context: it explains that returned events can be marked read to affect subsequent calls, and that the feed is persisted. This goes beyond what annotations provide, earning a high score.

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

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

The description is a single cohesive paragraph of five sentences, each serving a purpose. It is front-loaded with the primary action. While it lacks structural elements like bullet points, it remains concise and informative without redundancy.

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

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

Given the lack of output schema, the description thoroughly explains the return fields (source, citation_uri, raw event payload). It covers all five parameters, notes the persistence of the feed, and provides alternative access. For a read-only polling tool with good annotations, this is a complete and self-contained description.

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

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

The input schema has 100% description coverage, but the description adds value by elaborating on parameter semantics: e.g., 'mark_read:true to flag returned events read so the next call only shows newer ones' and 'Filter by type (e.g. "sec_8k")'. This enhances understanding beyond the schema's brief descriptions.

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

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

The description starts with 'Pull fired events from your subscription feed', which is a clear verb+resource pairing. It specifies the return fields and filtering options, making the tool's function unambiguous. However, it does not explicitly distinguish this tool from siblings like 'list_subscriptions' or 'subscribe', which could cause confusion.

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 mentions that 'Polls work fine' and that the same feed is available via a direct API endpoint for scripts/dashboards, implying this tool is suitable for conversational polling. However, it does not provide explicit when-to-use guidance relative to sibling tools, nor does it exclude scenarios where other tools might be better.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable detail about parallel fan-out, fallback logic, and soft-fail behavior, going beyond what annotations provide.

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

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

The description is front-loaded with user intent examples, includes all necessary behavioral details, and is structured well. It is slightly lengthy but every sentence adds value; no redundancy.

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

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

Given the complexity of multiple data sources, fallback mechanism, and window parameter, the description fully covers usage, expected output structure, and constraints. No output schema is provided, but the description explains the return format sufficiently.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances parameter meaning by explaining the 'since' format (ISO date vs relative shorthand) and clarifying that 'type' is currently limited to 'company', adding practical value.

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

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

The description clearly states the tool provides a change feed for a company over a time window, listing specific sources (SEC, GDELT/GNews, USPTO) and explicitly contrasts with the sibling tool entity_profile 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?

The description gives concrete usage examples (e.g., 'latest on Y', 'updates on Acme'), explains the window syntax, and explicitly advises when to use entity_profile instead, providing clear guidance on 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 indicate write operation (readOnlyHint=false), idempotent (idempotentHint=true), non-destructive (destructiveHint=false). Description adds scope and persistence details (authenticated vs anonymous, 24-hour retention) beyond annotations. No contradictions, but lacks mention of potential limits or failure modes.

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

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

Four sentences with no wasted words: first states purpose, second provides usage context, third gives technical details, fourth mentions related tools. Front-loaded and clear.

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 explains what is stored, persistence behavior, and relates to sibling tools. Complete for a simple key-value store 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 covers both parameters with descriptions (100% coverage). Description reinforces key naming conventions ('subject_property') and value usage ('any text'), adding marginal value 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?

The description clearly states the tool's purpose with a specific verb ('Save') and resource ('data'), and distinguishes it from siblings like 'recall' and 'forget' by explicitly mentioning them for retrieval and deletion.

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

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

Provides explicit guidance on when to use ('when you discover something worth carrying forward') and what constitutes worth carrying forward (resolved ticker, target address, etc.). Also mentions pairing with recall and forget, and scoping by identifier.

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

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

Beyond the readOnly/idempotent annotations, the description discloses key behaviors: unresolved identifiers are explicitly reported rather than omitted, LEI/FIGI enrichment degrades gracefully when GLEIF/OpenFIGI is unavailable, and internal cascading across endpoints occurs. These traits help an agent predict side effects and fallback 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 front-loaded with user intents and purpose, then organized by supported types. It is lengthy but each section explains distinct details (identifiers, sources, unresolved handling, degradation). Minor redundancy in example phrases could be trimmed, but the structure is logical and 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 moderately complex tool with two types and multiple identifier sources, the description covers purpose, input variants, output highlights, error behavior (unresolved field), fallback, and internal cascade. Without an output schema, this gives the agent a robust mental model for expected results.

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

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

Schema coverage is 100%, but the description adds rich meaning to both params. For `type`, it enumerates 'company' and 'drug' and explains what identifiers each returns; for `value`, it gives input formats (ticker, CIK, name) and examples. This goes well beyond the schema's short descriptions.

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

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

The description clearly states the tool's function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It includes specific user query examples and names the entity types, distinguishing it as the go-to tool for name-to-ID conversion. It also differentiates from siblings via 'Use FIRST whenever you have a name but need an ID.'

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

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

Explicit guidance is provided: 'Use FIRST whenever you have a name but need an ID.' It gives concrete example prompts that signal when to invoke, and notes that it 'replaces 2-3 manual lookups,' setting expectations for selection over 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, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: it internally calls ai_visibility_check per entity and returns a ranked list with score, confidence, signal density. No contradictions.

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

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

Two sentences, front-loaded with the main action and output. No filler; every sentence adds value. Structure is ideal for quick comprehension.

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

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

Given the tool's complexity (multi-entity comparison, ranking, multiple models), the description covers key aspects: input, process, output, and use case. No output schema, but return structure is described. Minor gap: no mention of error handling or model selection details.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantics: 'First entry treated as the subject for narrative' and explains that 'context' is a shared context for disambiguation. This adds value beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single) and compare_entities (general comparison).

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

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

Explicitly indicates use for competitive AI-marketing audits with an example question. Provides context but doesn't explicitly state when not to use or mention alternatives, though sibling differentiation is 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?

Discloses composite nature, partial failure behavior (sources_failed list, timing for bundlephobia), and return structure. Annotations already declare read-only and idempotent, but the description adds valuable operational details.

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

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

Single, well-structured paragraph that front-loads the key purpose, then covers usage, ecosystem scope, and failure handling. Every sentence adds value with no redundancy.

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

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

Covers composite nature, return fields, partial failures, and ecosystem limitations. Without an output schema, the description adequately describes the return data. Minor gap: format of advisories and links not detailed, but overall 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. The description adds value by noting that scoped packages are accepted for the 'package' parameter, which is not in the schema. 'version' semantics are clear from schema, but the extra note on scoped packages justifies above baseline.

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

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

The description clearly states the tool's purpose: a composite check for evaluating npm packages using deps.dev and bundlephobia. It specifies the verb 'scan' and resource 'dependency', and distinguishes it from sibling tools by focusing on npm ecosystem and specific data sources.

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 (e.g., 'is X safe / popular / small' or 'what does adding lodash cost me') and when not to use (non-npm ecosystems fall under different tools). Provides clear context for agent decision-making.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds technical details: BGE-base-en embeddings, cosine similarity over 500-char windows, 200K char cap with truncation, and that passages include offsets. This adds significant behavioral context.

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

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

The description is a single focused paragraph, front-loaded with purpose, then usage, then technical details. Every sentence serves a clear purpose with no 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?

Despite no output schema, the description explains return format (passages with offsets and scores) and technical constraints. It covers inputs, behavior, and pairing with another tool, making it complete for effective use.

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

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

Schema coverage is 100%, but description enriches parameters with practical examples (SEC 10-K, article) and usage tips. It adds meaning beyond the schema without being redundant.

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

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

The description clearly states the verb 'search inside a fetched record' and the resource, with a specific purpose of extracting relevant passages. It distinguishes itself from sibling tools like 'ask_pipeworx_grounded' by explicitly mentioning how they pair.

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 (when record is too large for prompt) and how it pairs with ask_pipeworx_grounded. It lacks explicit when-not guidance but provides clear context for usage.

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

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

The description discloses important behavioral traits beyond annotations: OAuth requirement, SMS rate limits (10/day), webhook secret returned once, and auto-disable for failing webhooks. Annotations are consistent (readOnlyHint=false, destructiveHint=false). The description adds valuable context that annotations alone do not provide.

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

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

The description is relatively long but every sentence adds value. It is front-loaded with the core purpose and then details specific types and delivery options. For a tool with multiple complex parameters, this level of detail is appropriate and not wasteful.

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

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

Given 3 parameters, 100% schema coverage, no output schema, the description fully covers return value, all input types, delivery channels, authentication, rate limits, and post-creation behavior. Nothing essential is missing.

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

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

Schema coverage is 100%, but the description adds significant meaning with concrete examples for each type and delivery channel. It explains validation rules (e.g., phone must be verified) and behavior (webhook signing). This goes beyond the schema's brief 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 'Create a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id.' This is a specific verb+resource combination that distinguishes it from sibling tools like 'unsubscribe' and 'list_subscriptions.'

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

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

The description explicitly lists prerequisites ('Requires a Pipeworx OAuth account'), supported event types with examples, and delivery channel details. It provides clear context for when to use this tool, though it does not explicitly mention when not to use it or compare with 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, openWorldHint, idempotentHint, destructiveHint. The description adds context about the returned content (category-bucketed examples from a live catalog) without contradicting annotations. No behavioral surprises.

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 relatively long but every sentence adds value. It front-loads the purpose and alternatives. Slightly verbose but clear and well-structured.

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

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

Given the simple tool (one optional param, no output schema, clear annotations), the description is fully complete: it explains what it returns, when to use it, and how to use the parameter. No gaps.

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

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

Schema coverage is 100%, and the description adds value by listing valid focus areas (finance, pharma, etc.) and explaining the effect of omitting the parameter, going beyond the schema description.

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

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

The description explicitly states it is the onboarding entry point, returning category-bucketed example questions with tool+argument shapes. It clearly distinguishes from sibling tools like ask_pipeworx (which performs actual queries) and discover_tools.

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

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

Directly advises to use this tool FIRST when the user does not know what Pipeworx can do, or to learn how to call meta-tools. Also explains when to omit or pass the topic parameter.

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

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

The description adds significant behavioral context beyond annotations: ownership enforcement, idempotent deactivation, and preservation of history. 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?

Three succinct sentences with no fluff, front-loaded with the core action and key constraints.

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

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

The description fully covers the tool's purpose, constraints, and side effects for a simple 1-parameter tool with no output schema.

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

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

Schema coverage is 100%, and the description adds value by noting the id is a UUID from subscribe, linking parameter to context. Baseline 3, slight improvement.

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) and resource (subscription by id), distinguishing it from sibling tools like subscribe and list_subscriptions.

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 ownership enforcement and the deactivation behavior (not deletion), guiding when to use this tool. It does not explicitly mention when not to use it, but 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?

Beyond the readOnly/openWorld/idempotent annotations, the description adds critical behavioral nuance: the distinction between 'could_not_verify' (failure to check, not evidence) and 'unsupported' (no source exists), the routing logic (structured vs grounded), and the return contract (verdict, actual value, citation, reasoning). This is high-value context not inferable from annotations.

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

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

Although longer than average, every sentence earns its place. It front-loads with colloquial triggers, then layers technical behavior (two paths, return values, error semantics) in a logical order. The 'IMPORTANT for callers' callout is well-placed. No fluff or redundancy.

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

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

Given the tool's complexity (dual routing, special verdict meanings, no output schema), the description is complete: it explains the return structure, error handling, source coverage, and the efficiency benefit. The absence of an output schema is compensated by explicit verdict and citation descriptions. Nothing critical is missing.

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

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

The input schema covers 100% of parameters, so the baseline is 3. The description adds meaningful details: it explains the tolerance_pct override for hallucination detection, states the default (implied by wording, capped at 5), and gives a concrete usage scenario. This goes 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 opens with a clear list of natural-language triggers ('Is it true that...', 'fact check', etc.) and states the tool performs 'natural-language claim verification against authoritative sources.' This specific verb+resource combination distinguishes it from sibling Q&A tools, and the mention of replacing 4–6 sequential calls clarifies its unified purpose.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates internal paths: company-financial claims via SEC EDGAR/XBRL, and all other factual claims via a grounded pipeline. It does not explicitly mention when NOT to use this tool versus siblings like ask_pipeworx_grounded, but the primary trigger is clear.

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