Tastedive

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint. The description adds value by detailing default model, cost implications of Anthropic key, and return structure (per-model score, confidence, signals, raw_response plus combined view). This goes beyond annotations.

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

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

The description is two sentences, both dense with information. First sentence covers core function and output; second covers defaults, optional key, and use cases. No wasted words 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 no output schema, the description adequately covers return values (per-model and combined). It explains parameter interplay (default model, key requirement). Missing details like error handling or confidence derivation, but sufficient for agent selection and invocation.

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

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

All 4 parameters are described in the schema (100% coverage). The description adds practical semantics: default model for 'models' parameter, BYO key for '_apiKey', disambiguation for 'context'. This enriches understanding beyond schema descriptions.

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

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

The description clearly states the tool probes LLMs for brand/business visibility and scores it per model (0-100). It specifies default model, optional Anthropic probe, and output structure. The verb 'probe' and noun 'visibility' are specific, and the purpose is distinct from siblings like scan_competitor_ai_presence.

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

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

The description explicitly mentions use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), giving clear context. However, it does not contrast with alternatives like scan_competitor_ai_presence or state when not to use, so it's not a full 5.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds that the tool routes to the correct tool, fills arguments, and returns structured answers with stable URIs. It does not disclose rate limits or auth needs, but the annotations cover the safety profile adequately.

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 key preference and structure. It uses clear sections and examples. While lengthy, every sentence adds value, though it could be slightly more concise without losing clarity.

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 the tool (routing to many sources), the description covers return format (structured answer with citation URIs), usage context, and differentiates from 30+ sibling tools. It is complete for an AI agent to decide when to invoke this 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% with descriptions for all parameters and aliases. The description adds value by specifying expected input (natural language factual questions) and providing examples, which helps the AI agent formulate valid queries beyond the raw schema.

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

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

The description explicitly states the tool routes factual questions to 5,008 tools across 1,318 sources and returns structured answers with citations. It clearly distinguishes from sibling tools like ask_pipeworx_grounded and deep_research by specifying when each should be used.

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

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

The description provides explicit guidance on when to prefer this tool over alternatives (e.g., 'PREFER OVER WEB SEARCH'), includes a list of example queries, and clearly states when to step up to other tools (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad multi-part questions).

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, openWorldHint, idempotentHint, destructiveHint false. Description adds that it is a full working router but experimental, and explains fallback behavior (falls back to nothing) and source-preference ranking. 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 fairly concise and front-loads key info (beta, identical to ask_pipeworx). There is slight redundancy (e.g., 'identical universal router' and 'same 5,008 tools, same arguments, same response shape'), but overall 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 no output schema, the description mentions the response shape is same as ask_pipeworx, which is adequate. It addresses the beta nature and experimental features sufficiently for an AI agent to understand the tool's purpose and behavior.

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

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

Schema coverage is 100% with detailed schema descriptions for all parameters. The description does not add significant new meaning beyond the schema, as the source-preference feature is about question content, not parameters. 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 identifies it as a beta version of ask_pipeworx, an identical universal router with 5,008 tools and same arguments/response. It distinguishes itself from siblings by mentioning candidate routing improvements and source-preference ranking.

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 to use it exactly like ask_pipeworx when you want the newest routing, and explains the experimental source-preference feature. However, it does not explicitly state when not to use it or mention the stable router as an 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description goes beyond by detailing the tool's refusal behavior, including specific refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error) and the return format (answer, evidence, confidence, source, fetched_at). It also discloses the cost of an extra LLM call, which is valuable 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 somewhat lengthy (3-4 sentences) but each sentence provides essential information: purpose, behavior, return format, usage guidance, and cost trade-off. It is front-loaded with the key concept 'Hallucination-resistant answer mode' and structured logically. Minor room for trimming, but overall effective.

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

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

Given the tool's complexity (large sibling set, high-stakes use, no output schema), the description is remarkably complete. It covers purpose, return format (including evidence and refusal reasons), usage guidelines, and performance trade-offs. No output schema exists, but the description compensates by detailing the return structure explicitly.

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

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

Schema description coverage is 100%, with all parameters being aliases for the single required 'question' parameter. The description adds value by stating that the tool accepts natural language and lists aliases (query, q, prompt, text, input), which helps the agent understand parameter flexibility. However, the schema already documents each alias's description, so the added value is moderate.

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: 'Hallucination-resistant answer mode for high-stakes reads.' It explains that it extracts answers only from tool results, providing exact quotes and evidence. It also distinguishes itself from ask_pipeworx by noting the extra LLM call and the use case for high-stakes 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 explicitly tells when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It provides concrete examples like financial verdicts, legal claims, medical lookups, and public statements. It also advises preferring ask_pipeworx for casual lookups, offering clear guidance on choosing between siblings.

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

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

The description goes far beyond annotations (readOnlyHint, idempotentHint, etc.) by detailing resolution contract (match confidence, alternatives), parent event extractor, news fallback mechanisms, safety short-circuits (low-confidence, closed markets), spread warnings, and resolution-rule risk. No contradiction with annotations.

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

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

The description is lengthy but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads the core purpose in the first sentence. Some redundancy could be trimmed, but the detail is largely justified by the tool's complexity.

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

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

No output schema exists, so the description must cover return values. It extensively documents result structure (market, analysis, evidence), edge cases (low-confidence, closed markets, wide spreads), and resolution-rule risk. Given the tool's complexity (multiple classifiers, fan-outs), the description is thorough.

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

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

Schema description coverage is 100%, and the description adds significant meaning: explains market input formats, depth options (quick vs thorough with evidence count), and include_raw parameter with rationale for defaulting to false. This adds context 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text), the process (resolve, classify, fan-out, return evidence + comparison), and distinguishes from sibling tools by focusing on single-bet research with extensive details.

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

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

The description explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it doesn't explicitly state when not to use or name alternatives, the usage scenarios are clear and practical.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint. The description adds critical context: it pulls latest 10-K data from SEC EDGAR/XBRL with correct fiscal year handling, sorts results by primary metric, and returns citation URIs. No contradictions.

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

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

The description is front-loaded with example queries and core purpose, but contains some redundancy (multiple ways to phrase comparison). Overall, every sentence adds value, but could be slightly more concise without losing clarity.

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 values (paired data + citation URIs) and covers both entity types. All required parameters are documented, making the tool fully understandable for selection and invocation.

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

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

Schema coverage is 100%. The description adds meaning beyond the schema by explaining what each type retrieves (financials vs adverse-event counts) and how to format values (tickers/CIKs vs drug names). It also clarifies output ordering.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in one parallel call, listing specific example queries. It distinguishes itself from sibling tools by noting it replaces 8-15 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 tells when to use this tool (e.g., 'compare X and Y', 'rank these companies') and strongly advises preferring it over sequential single-pack lookups. It provides clear instructions for parameter usage based on type.

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 key behaviors: it doesn't invent (gaps[] for unanswered facets), execution time (15-60s, up to ~90s for thorough), hop iteration, contradictions[] flagging, semantic excerpting of large records, and citation URIs. Annotations already indicate readOnly, openWorld, idempotent, non-destructive; the description adds rich context beyond annotations.

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

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

The description is lengthy but well-structured: it front-loads account requirements and alternatives, then explains core functionality, then details depth options and iteration. Every sentence adds value, though some minor trimming could improve conciseness given 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 complexity (2 parameters, no output schema, rich annotations), the description is thorough. It covers account constraints, alternatives, execution time, return format (findings packet, gaps, contradictions), depth behavior, and citation details. It provides enough context for an AI to select and invoke the tool correctly.

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

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

Schema coverage is 100% for both parameters. The description adds meaning: it explains what each depth level does (quick=3, standard=5, thorough=8) and that question can be broad/multi-part because decomposition is the point. It details behavior differences between depth levels (gap recovery, contradictions), which goes 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: 'Grounded multi-source research across Pipeworx's 1318 STRUCTURED data sources in ONE call'. It specifies the decomposition into facets, parallel tool routing, and output format. It distinguishes from ask_pipeworx (single lookup) and provides context for when to use alternatives.

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

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

The description explicitly guides when to use this tool vs. alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also notes account requirements (free sign-in, paid plan for thorough depth) and suggests using ask_pipeworx if not signed in.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds valuable behavioral context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains the return structure and reusability. Good but not exhaustive.

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

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

Description is efficient with front-loaded purpose. Uses bullet-like lists and brief sentences. Some redundancy (e.g., multiple alias mentions) but overall clean 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?

Covers what the tool returns (tools with schemas), when to use, and input format. Missing explicit mention of default/max limit, but those are in the schema. No output schema, so description adequately explains the result. Slightly incomplete for a discovery tool but 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?

Even though schema coverage is 100%, the description adds meaning by explaining the query parameter as 'Natural language description of what you want to do' and listing aliases ('task, q, description, search'). Provides examples like 'analyze housing market trends' which clarify expected input.

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 'Find tools by describing the data or task.' Provides explicit verb ('find'), resource ('tools'), and scope. Distinguishes from sibling tools like specific data tools or research tools; this is the discovery/gateway 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?

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and provides concrete examples. Also advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' giving clear usage context and exclusions.

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

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

Annotations already indicate safe, non-destructive, idempotent behavior. The description adds value by detailing the parallel fan-out across multiple sources, specific return fields, and a caveat about the patents API sunset May 2025. 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 a single dense paragraph that front-loads example queries and usage preference. It is efficient with no wasted sentences, though it could be slightly restructured for readability. Overall, it earns its place.

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

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

Given no output schema, the description comprehensively explains the return values: CIK, company name, recent filings with URIs, fundamentals sorted, patents with fallback, news, and LEI. It covers all key aspects of the tool's complex behavior.

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 guidance beyond the schema by clarifying that only ticker or zero-padded CIK are accepted, and names are not supported. It also suggests using resolve_entity first, which adds value for the agent.

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 provides a full cross-source profile of a US public company in one parallel call, with specific examples of user queries. It distinguishes from sibling tools like resolve_entity by specifying that names are not supported and that resolve_entity should be used first.

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: when a holistic view is needed, and when not to: avoid chaining single-pack lookups. Also provides alternative: use resolve_entity for names. This is exemplary usage guidance.

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

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

The description matches the destructiveHint annotation by stating 'Delete'. It adds context about clearing sensitive data. However, it does not address idempotency (idempotentHint) or behavior when the key doesn't exist.

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

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

The description is two sentences, front-loaded with the primary action, and no wasted words.

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

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

For a simple one-parameter tool with annotations covering destructiveness, the description is largely complete. Missing details like error handling or idempotency are minor given the simplicity.

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

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

Schema coverage is 100% and the parameter description is clear. The tool description does not add additional meaning beyond what the schema provides.

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

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

The description clearly states the action ('Delete'), the resource ('memory'), and the method ('by key'). It distinguishes from siblings by mentioning 'remember' and 'recall'.

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 scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with other tools for context.

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 the fetch, extraction, and emission process beyond annotations. Annotations are consistent, and the description adds value by specifying the output format and readiness for deployment.

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 fluff. Every sentence contributes to understanding.

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

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

Despite no output schema, the description explains the output format (llms.txt markdown blob). It covers the entire workflow and is sufficient for an agent to use correctly.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds minimal extra meaning beyond what the schema provides (e.g., explaining that max_links defaults to 25 and max 50 is already in schema).

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

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

The description clearly states the tool generates an llms.txt file for AI crawlers, using specific verbs and resources. It differentiates from sibling tools by focusing on a specific output format and use cases.

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

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

The description lists concrete use cases (indexing clients, drafting for own project, auditing competitors). It does not explicitly mention when not to use, but the context is clear and no alternative sibling tools exist for this task.

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, so the safety profile is fully covered. The description adds minor behavioral context (uses TasteDive API, returns specific fields) but does not significantly expand on what annotations already 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 two sentences long, front-loaded with the primary purpose, and contains no superfluous words. Every sentence adds value.

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

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

Given the tool has 4 parameters (with 100% schema coverage), annotations, an output schema, and examples in the input schema, the description provides sufficient context for an AI agent to understand what the tool does and how to use it.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description adds minimal additional meaning beyond restating the schema's information (e.g., 'comma-separated titles', 'optionally restrict to one media category'). Baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Return') and resource ('recommendations'), clearly states the source (TasteDive), and specifies the input format (seed query, comma-separated titles) and optional restriction by media category. It distinguishes this tool from siblings like search or research tools.

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

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

The description clearly implies when to use this tool (to get 'similar to X' recommendations). It does not explicitly state when not to use it or provide alternative tools, but the context of sibling tools and the clear purpose make usage straightforward.

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

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

Annotations already declare readOnlyHint and destructiveHint. The description adds context about return fields and the scope of active subscriptions, which is valuable beyond annotations.

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

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

Two succinct sentences: first states purpose and return fields, second provides usage guidance. No unnecessary information.

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

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

For a simple list tool with one optional parameter, the description covers purpose, usage, return fields, and integrates well with annotations. Sufficient for an AI agent.

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

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

Schema coverage is 100% with a good description for include_inactive. The tool description does not elaborate on the parameter but also does not mislead. Baseline score is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the return fields. It 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?

Provides explicit guidance: use before adding more subscriptions or to get an id for cancellation. Does not mention when not to use, but the context is clear.

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

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

Discloses rate limiting (5 per identifier per day), team review cadence (daily), and roadmap impact. Annotations are neutral (no hints), but the description provides essential behavioral 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?

Four sentences, front-loaded with the core action, then usage conditions, then behavioral notes. No redundant or unnecessary 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?

Covers all necessary aspects: what the tool does, when to use each type, constraints (rate limit, no prompt pasting), and outcomes (roadmap impact). No output schema needed as feedback confirmation is implied.

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

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

Schema has 100% description coverage. The description adds valuable guidance: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which provides nuance not in the schema.

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

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

The description clearly states the tool's purpose: to send feedback about bugs, missing features, or praise. It distinguishes itself from sibling tools which are all query/action tools, making this the sole feedback mechanism.

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

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

Explicitly describes when to use each feedback type ('Use when a tool returns wrong/stale data...'), and notes it is free and not quota-counted. No alternative tools exist, so no exclusions needed.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: data source (CF analytics-engine), no PII, and caching behavior (5min-1h). 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 plus a bullet list, with no wasted words. Main functionality is front-loaded, and every sentence earns its place by adding distinct value.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers return values, data source, privacy, caching, and use cases. It is fully sufficient for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100% with detailed enum description. The description adds meaning by explaining the trade-off between windows ('shorter windows surface what's hot right now; longer windows show steady-state demand'), which goes beyond the schema's definition.

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 top tools, packs, and call volume over a window. It specifies the verb 'returns' and the resource 'trending data on Pipeworx', distinguishing it from siblings like 'discover_tools' or 'ask_pipeworx'.

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

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

The description explicitly lists three use cases: discovering hot data sources, confirming a popular tool, and seeing alignment with use case. It provides clear context for when to use, though it does not explicitly state when not to use.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true. The description adds extensive behavioral context: internal checks (monotonicity, partition-sum, semantic anchor with Jaccard similarity, partition filter for placeholder slugs), fill check against CLOB depth, and conditions for valid trade signals. No contradiction with annotations; the description enriches understanding beyond the structured hints.

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

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

The description is long but well-structured: first sentence summarizes, then sections for event mode and topic mode detail internal mechanisms. It includes concrete examples for slugs and seed questions. While somewhat verbose, every sentence adds value for correct usage. Could be slightly more concise but appropriate given 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?

Despite no output schema, the description thoroughly explains the response structure (opportunities[] with gap_pp, suggested_trade, reasoning; partition_check object; fill check details). It covers edge cases (skipped_low_similarity, placeholder filter, realizable edge ≤ 0). The description makes the tool fully understandable for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant meaning: for 'event', it explains acceptable formats (slug or full URL) and that it walks child markets; for 'topic', it explains cross-event search and flattening. The description also links parameter choices to different analysis modes, greatly enhancing utility beyond schema alone.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three invocation modes (trending_scan, event, topic) and specifies the resource (Polymarket markets). The verb 'find' plus detailed explanation of mechanisms provides precise purpose, differentiating it from siblings like polymarket_edges or polymarket_fill_risk.

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

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

Explicitly states when to use each mode: call with NO args for trending_scan of top ~200 markets; pass 'event' for a specific market slug; pass 'topic' for cross-event scanning. It recommends 'event' for specific markets and 'topic' for cross-event scans. Also provides guidance on when not to act (realizable_edge_pp ≤ 0 means do not trade) and directs to polymarket_fill_risk for custom sizing.

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 details behavioral traits beyond annotations, including caching (1h at KV level), response structure (by_segment, diagnostics), model families, slippage, Kelly fractions, and filter effects. Annotations (readOnlyHint, idempotentHint, etc.) are consistent with the description, which adds extensive 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 very long and dense, packed with technical detail. While front-loaded with purpose, it could be more concise; the extensive detail may overwhelm agents despite being informative.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (by_segment, diagnostics, fed_candidates) and behavioral traits (caching, filters, edge calculations), providing sufficient context 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?

With 100% schema description coverage, the baseline is 3. The tool description adds value by explaining how each parameter affects results (e.g., min_liquidity, max_spread_pp, min_partition_leg_kelly) and their interaction with edge knobs, enhancing understanding beyond schema.

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

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

The description clearly identifies the tool as scanning Polymarket markets for edge opportunities where Pipeworx data disagrees with market price, distinguishing it from sibling tools like polymarket_arbitrage and polymarket_kalshi_spread.

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 'Built for "what should I bet on today"' and describes tradeable-edge knobs and filters, providing clear context for use. It does not explicitly exclude alternatives but implies the tool is for discovering opportunities without paging through markets.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds critical behavioral context: data gaps due to cache-miss snapshots, TTL of 60 days, decay computation from daily closes (not intraday), and signed edge values. 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?

Description is long but well-structured with clear sections (RESPONSE, LIMITS). Every sentence provides unique value. Could be slightly tighter, but effective for a complex tool.

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

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

No output schema exists, so description fully covers return structure: tracked[], expired[], snapshot_dates[]. Also explains limitations like TTL and data gaps. Complete for a tool with 2 optional parameters.

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

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

Input schema already describes both parameters (days, window) with defaults. Description reinforces these, adds clamping behavior (days clamp 2-30, window default '1wk'), and explains how parameters affect the returned data (lookback, snapshot family). 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?

Description clearly states it provides edge persistence and decay telemetry, answering specific questions about edge duration and trend. It distinguishes itself from the sibling 'polymarket_edges' tool by focusing on historical persistence rather than current snapshots.

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?

Implicitly differentiates from sibling 'polymarket_edges' by focusing on persistence and decay. Includes usage notes on history depth and data gaps, but lacks explicit when-to-use vs alternatives or when-not-to-use conditions.

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 goes beyond by detailing the internal behavior: 'walks the ladder and returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict.' It also warns about forced directional risk, adding significant transparency without contradicting annotations.

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

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

The description is fairly long but well-structured with clear mode separation (SINGLE-MARKET vs BASKET) and all-caps key points. Every sentence adds value; the length is justified by the tool's complexity. Minor reduction possible but not detrimental.

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

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

There is no output schema, but the description fully explains the return fields for both modes, including concepts like capture_ratio, thin_legs, and forced_directional_risk. Given the rich annotations and complete parameter coverage, the description leaves no gaps in understanding the tool's behavior.

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

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

Schema coverage is 100% (all 4 parameters described). The description adds substantial meaning beyond the schema: it clarifies that market and event are mutually exclusive ('REQUIRES one of market or event'), explains how side works differently in each mode, and elaborates on size_usd interpretation (max spend vs target proceeds for single-market, settlement notional for basket).

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly distinguishes between single-market and basket modes, and its usage is tied to specific sibling tools (polymarket_arbitrage, polymarket_edges), avoiding ambiguity.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (thin books, partial fills leading to unhedged positions), effectively telling when to use and when to avoid.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context: compatibility warnings, temporal alignment checks, skipped cross types, and how the tool signals when no arb exists. It does not contradict annotations.

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

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

The description is well-structured with front-loaded purpose, clear sections for modes, response fields, and safety warnings. While thorough, it is slightly verbose with some repetition (e.g., explaining compatibility warning twice). Still, every sentence adds value.

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

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

Given the tool's complexity (cross-venue matching, temporal alignment, compatibility checks) and no output schema, the description adequately explains response fields (leg-by-leg prices, top spreads, safety fields like compatibility_warning and temporal_alignment). It equips the agent to interpret results correctly.

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

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

Schema description coverage is 100% with all three parameters having descriptions. The tool description adds usage context (e.g., topic mode vs explicit override, how topic auto-fetches events) which helps the agent understand parameter interactions beyond what the schema provides.

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

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

The description clearly states the tool's purpose: computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It uses a specific verb (cross-venue spread) and resource (two prediction markets), and distinguishes from sibling tools like polymarket_arbitrage which focuses on a single venue.

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 defines two modes (topic shortcuts and explicit ticker pairs), provides examples, and warns about when spreads are meaningless (temporal misalignment, shape mismatch). It also notes that most pre-mapped topics are not tradeable, guiding agents away from false expectations.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds scoping details ('Scoped to your identifier...') and behavior when omitting the key (lists all keys). No contradiction, and it enriches understanding beyond structured fields.

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

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

The description is three sentences, front-loading the core purpose, then adding usage guidance and scoping. Every sentence adds value without redundancy or wasted words.

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

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

Given a single optional parameter, full annotations, and no output schema, the description covers behavior (omitting key, listing), scoping, and relationships to siblings. It is complete for the tool's simplicity.

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

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

Schema coverage is 100% with clear description of the 'key' parameter. The description restates that omitting key lists all keys, which matches the schema. Baseline 3 is appropriate as the description adds no new parameter-level insight 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 uses specific verbs ('Retrieve', 'list') and clearly identifies the resource (values saved via 'remember', keys). It distinguishes from siblings by naming 'remember' and 'forget', making the tool's role unmistakable.

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

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

The description explains when to use the tool ('look up context the agent stored earlier') and implies an alternative ('without re-deriving it from scratch'). It does not explicitly exclude cases, but the context is clear. It pairs with 'remember' and 'forget' siblings, which is helpful.

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 safe, read-only, idempotent operation. Description adds details on return format and the effect of setting mark_read, consistent with annotations. 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?

Four concise sentences, front-loaded with purpose, then key details, then usage tips. No redundant information.

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

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

Explains output structure, polling suitability, and alternative access method. For a read-only tool with no output schema, this is sufficient. Minor gap: no explanation of what happens when no alerts match.

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

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

Schema covers all parameters with descriptions; description adds value by giving concrete filter example ('sec_8k'), clarifying 'since' as ISO timestamp, and explaining mark_read behavior.

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 pulls fired events from a subscription feed, specifies the returned fields (source, citation_uri, raw payload), and distinguishes it from sibling tools like 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?

Provides guidance on using mark_read to manage read state, notes polling compatibility, and mentions an alternative REST endpoint. Lacks explicit when-not-to-use 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?

Annotations already indicate safe read-only behavior, but the description adds rich behavioral detail: parallel fan-out, GDELT→GNews fallback on rate limits/5xx, USPTO soft-fail, and return structure. No contradictions with annotations.

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

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

While the description is somewhat lengthy, every sentence adds value. It is well-organized with examples and clear guidance. A slight trim could improve conciseness, but it remains 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?

Despite lacking an output schema, the description fully explains the return format, fallback behaviors, and error handling. It also provides an alternative tool. For a moderately complex tool, this is thorough.

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 extra context: since accepts ISO or relative shorthand with examples, value accepts ticker or CIK, type limited to company. This goes beyond the schema descriptions.

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

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

The description clearly states the tool aggregates changes from multiple sources (SEC, GDELT/GNews, USPTO) in one call, with specific examples of user queries. It explicitly distinguishes from the sibling tool entity_profile, making the purpose unmistakable.

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

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

Provides concrete example queries ('What's new with X'), explains fan-out behavior, fallback logic, and when to use entity_profile instead. Also gives parameter guidance (e.g., 'Use "30d" or "1m" for typical monitoring').

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 idempotent (can repeat) and not destructive. The description adds valuable context: persistence (authenticated users vs. 24-hour anonymous), scope by identifier, and that it's a write operation. 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?

Four sentences front-loaded with purpose, then usage, then behavioral details. No unnecessary words; every sentence adds value.

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

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

Given the tool's simplicity (key-value store, no output schema), the description covers all needed aspects: purpose, usage context, pairing, persistence, and scoping. Nothing 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% with good descriptions. The description adds example values (findings, addresses, preferences, notes) that complement the schema's examples, providing extra guidance without redundancy.

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

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

The description states the tool saves data for later reuse, specifying it stores key-value pairs scoped by the agent's identifier. It clearly distinguishes from sibling tools like recall and forget, making the purpose unambiguous.

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

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

The description advises using when discovering something worth carrying forward and mentions pairing with recall and forget. It lacks explicit when-not to use, but the guidance is clear and practical.

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

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

Annotations already mark readOnlyHint, idempotentHint, destructiveHint, openWorldHint. Description adds valuable context: internal cascading lookups replacing 2-3 manual steps, and explains return format for each type. 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 paragraphs, front-loaded with example queries. Every sentence adds value. Could be slightly more concise but overall 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?

Covers main use cases, return format, and internal behavior. No output schema but description explains return fields. Lacks discussion of error cases or limitations (e.g., unresolved names), but given tool simplicity and annotations, it is fairly complete.

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

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

Schema coverage is 100% with enum and description. Description enriches by specifying input examples (ticker, CIK, name for company; brand/generic for drug) and details returned fields. Adds meaningful 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?

Description clearly states the tool resolves names to canonical identifiers, specifies supported types (company, drug) with examples of queries. Differentiates from siblings by positioning it as the first tool to use when having a name but needing 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?

Explicitly says 'Use FIRST whenever you have a name but need an ID.' Provides query examples. Does not explicitly state when not to use or mention alternatives among siblings, but 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 declare readOnlyHint, idempotentHint, openWorldHint, destructiveHint false. Description adds behavioral context: probes each entity, ranks results, returns ranked list with score, confidence, signal density per entity. 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: first front-loads core action, second adds usage example and output details. 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?

Covers purpose, usage, parameters, and output behavior. Lacks explicit output format structure but mentions rank, confidence, signal density. Given no output schema, this is adequate for an agent.

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

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

Schema coverage is 100%, so baseline 3. Description enriches by noting first entity treated as subject, context disambiguates names, and models parameter explains free vs paid options.

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

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

Description clearly states it compares AI visibility across multiple entities, probes with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

Explicitly says 'Useful for competitive AI-marketing audits' with an example question. While it doesn't list when not to use, the context implies use for comparing multiple entities, and sibling ai_visibility_check serves single-entity 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 already provide readOnly, idempotent, and non-destructive hints. The description adds beyond that: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed will list timeouts, and return structure details. 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?

The description is a bit long but each sentence adds necessary context. It is front-loaded with the core purpose and then provides details on behavior and limitations. Could be slightly more concise but not overly verbose.

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 a composite check across multiple services, the description thoroughly covers return structure (summary block, advisory detail, links, alternatives), partial failure handling, ecosystem limitations, and performance caveats. No output schema exists, so the description compensates well.

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 extra usage context: scoped packages are accepted, version defaults to latest, and explains the multi-source fan-out behavior. That adds value beyond the schema's parameter 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 as a composite check for npm packages using deps.dev and bundlephobia, specifying the verb 'scan' and resource 'npm package'. It distinguishes from siblings by noting that other ecosystems fall under deps.dev:version directly.

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 tells when to use: when an agent asks about safety, popularity, or size. Also provides when-not: NPM ecosystem only in v1; for others use deps.dev:version directly. This is clear 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 the tool is read-only, open-world, idempotent, and non-destructive. The description adds significant behavioral detail beyond annotations: it specifies the embedding model (BGE-base-en), similarity measure (cosine), window size (500-char overlapping), character cap (200K chars with truncation and flagging), and output characteristics (character offsets and similarity scores). 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 a single, well-structured paragraph that front-loads the primary purpose and then efficiently provides technical details (model, window, cap, pairing). Every sentence adds value without redundancy. It is concise yet comprehensive.

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

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

Even without an output schema, the description fully explains what the tool returns: top-N passages with character offsets and similarity scores. It also covers limitations (200K char cap, truncation flag) and use case context. For a search tool with three simple parameters, this is complete and leaves no ambiguity.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add any new information about parameters beyond what the input schema already provides (text, limit, query with descriptions and examples). While the description reinforces the purpose of each parameter, it does not enrich the semantics further. Therefore, score at 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 name 'search_within' and title 'Search Within a Source' clearly indicate the tool's function. The description explicitly states 'Semantic search INSIDE a fetched record' and distinguishes its role from the sibling tool 'ask_pipeworx_grounded' by explaining the pairing: fetch with the gateway and ground over passages. This meets the highest standard of specificity and sibling differentiation.

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

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

The description provides explicit guidance on when to use the tool: 'Use when the record is too big to cram into the prompt — search_within saves context.' It also explains the benefit: 'returns only the passages that matter' and recommends pairing with 'ask_pipeworx_grounded' for grounded reasoning. This covers both usage context and alternatives.

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

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

Annotations already indicate non-destructive, idempotent, and open-world traits. Description adds essential behavioral details: account requirement, type-specific parameters, delivery options with constraints (SMS cap, phone verification, webhook auto-disable). 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?

Description is front-loaded with the core action and goes into necessary detail for types and delivery. It is somewhat dense but every sentence adds value; could be slightly more concise, but still 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 tool's complexity (3 parameters, nested objects, no output schema), the description covers purpose, prerequisites, all types with examples, delivery channels, and important constraints. It provides enough information for an AI 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 already covers all parameters (100%), but description enriches each parameter with concrete examples (e.g., sec_8k items, polymarket topic) and delivery channel specifics (email, SMS, webhook with verification and signing). This deepens understanding 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 ('Create a proactive monitoring subscription') and the resource ('live-data event stream'). It distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation, and specifies it returns the subscription ID.

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

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

The description explicitly requires a Pipeworx OAuth account, ruling out anonymous/BYO users, and lists supported types with examples. It provides context for when to use the tool, but does not explicitly exclude alternatives or compare with siblings.

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

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

Description adds behavioral context beyond annotations: it is the onboarding entry point, returns example questions with exact tool calls, and is drawn from a live catalog. Annotations already indicate read-only, idempotent, non-destructive; description enriches this with specific 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 informative but slightly verbose, using multiple sentences that could be tightened. However, it is well-structured by starting with common queries, then purpose, then return value, then usage guidance.

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

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

The description fully covers the tool's functionality for its complexity (one optional parameter, no output schema). It explains return value (category-bucketed example questions) and use case, making it self-contained.

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

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

Despite 100% schema coverage, the description adds semantic value by enumerating example topic values (finance, pharma, etc.) and explaining the effect of omitting the parameter. This goes beyond the schema's bare description.

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

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

The description clearly states the tool returns category-bucketed example questions for Pipeworx, explicitly distinguishing it as the onboarding entry point from siblings like ask_pipeworx. It uses specific verbs and resources.

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 tells when to use this tool ('Use this FIRST when you do not yet know what Pipeworx can do for you'), and provides clear argument guidance: no arguments for full spread, or pass a topic to focus. This differentiates from sibling tools.

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

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

Annotations indicate non-destructive, idempotent write operation. The description adds that the row is deactivated (not deleted) and historical events remain available. This adds value beyond annotations without contradiction.

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

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

Two sentences, front-loading the core action and immediately following with crucial ownership and behavior details. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage constraint, and behavioral outcome 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 coverage is 100% with a clear description for the 'id' parameter. The description does not add extra semantics beyond what the schema provides, fitting the baseline for high coverage.

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

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

The description uses the specific verb 'Cancel' and resource 'subscription by id,' clearly stating the action and target. It distinguishes itself from tools like 'subscribe' by indicating the reverse operation.

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

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

The description explicitly states ownership enforcement: 'you can only cancel your own subscriptions,' providing clear context for when to use the tool. No alternatives are listed, but the constraint is well-defined.

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 significant behavioral context: the two processing paths, exact percent-delta math for financial claims, fallthrough logic, and the return structure (verdict categories, citation format, reasoning). It does not contradict annotations and provides valuable transparency 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 detailed and well-structured, front-loading the key purpose with examples and then explaining the mechanism. While slightly verbose (10 sentences), each sentence adds value, and the structure is logical. A minor trim could be made, but it remains 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?

Despite lacking an output schema, the description fully explains the return types (verdict with five categories, actual value with citation, reasoning). It covers the two processing paths and parameter overrides. The tool's complexity is well-matched by the description's completeness, making it self-contained for an agent.

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

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

Schema coverage is 100% with descriptions for both parameters (claim and tolerance_pct). The description enriches the semantics by explaining the default tolerance behavior (implied by wording, capped at 5), suggesting overrides for hallucination detection, and clarifying that 'claim' is natural-language. This adds practical usage guidance 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 defines the tool as a natural-language claim verifier against authoritative sources. It specifies the verb 'verify' and distinguishes it from siblings by describing its unique dual-path mechanism (SEC EDGAR for financial claims, grounded pipeline for others). It also explicitly states it replaces 4-6 sequential calls, making its purpose unmistakable.

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

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

The description explicitly states when to use: 'whenever the agent needs to check whether something a user said is factually correct.' It provides clear context but does not explicitly list alternatives or when not to use (e.g., for non-factual queries). However, the context is sufficient for an agent to select this tool over siblings for factual claims.

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