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 declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false. The description adds significant behavioral context: it routes to 3,436 tools, fills arguments, and returns structured answers with pipeworx:// citation URIs. This goes beyond the annotations.

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

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

The description is relatively long but front-loaded with the key guidance ('PREFER OVER WEB SEARCH'). Every sentence adds value, listing many use cases and explaining the routing mechanism. It avoids fluff but could be slightly more concise.

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

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

Given the tool's complexity (routing to 3,436 tools) and no output schema, the description adequately covers the main use case with ample examples. It does not discuss error handling or limits, but the examples and explanation are sufficient for most agent usage.

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

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

Schema description coverage is 100% with detailed parameter descriptions and aliases. The description does not add extra semantic information about the parameters beyond what is in the schema. Baseline 3 is appropriate.

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

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

The description clearly states that the tool routes questions to a large collection of tools and returns structured answers with citations. It distinguishes itself from web search by explicitly stating 'PREFER OVER WEB SEARCH' and lists numerous example query types (SEC filings, FDA data, etc.), making the purpose highly specific and actionable.

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

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

The description provides strong usage guidance by explicitly stating to prefer this tool over web search for factual questions about real-world entities. It lists trigger phrases and concrete examples. It does not explicitly state when not to use, but the positive guidance is clear enough.

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

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

The description details behavioral traits beyond annotations: it uses only tool results to extract answers, costs an extra LLM call, and returns a structured response with explicit refusal reasons. 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 well-structured and front-loaded, covering purpose, usage, behavior, and return format without redundancy. Slightly verbose but each sentence adds value.

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

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

Despite no output schema, the description fully explains the return structure, failure modes, and when to use the tool. It also covers the extra cost and refusal reasons, making the tool's behavior complete for an LLM.

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 each alias described. The description adds no additional semantic meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states that this tool provides a 'hallucination-resistant answer mode for high-stakes reads' and explains that it extracts answers only from tool results. It distinguishes itself from 'ask_pipeworx' by noting the extra LLM call and refusal reasons.

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 an answer will be quoted, cited, or acted on') and when not to prefer 'ask_pipeworx for casual lookups', with clear alternatives mentioned.

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 extensively covers behaviors: resolution, classification, fan-out to category-specific data packs, response shapes, safety mechanisms (low-confidence matches, closed markets, wide spreads), and edge cases (market_closed_or_inactive, low_confidence_match). This adds value beyond annotations which only provide readOnly, openWorld, idempotent hints.

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

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

The description is verbose but well-organized: starts with purpose, then classifiers, fan-out examples, response shapes, resolver contract, parent event extractor, news fields, safety. Each section adds value. Minor redundancy (e.g., multiple mentions of low-confidence paths) but overall efficient.

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

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

Given no output schema, the description thoroughly covers return shapes (market, analysis, evidence), edge cases, and safety mechanisms. It explains how to interpret results (e.g., inspect market_match_confidence before trusting analysis). Highly 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?

All three parameters have schema descriptions (100% coverage), so baseline is 3. The description adds meaning beyond schema: examples of market input, depth options with default (thorough), and include_raw recommendation (false). It explains how parameters affect 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's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and action (research with Pipeworx data), and distinguishes from siblings by focusing on evidence gathering and analysis for decision-making.

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

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

The description provides explicit use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It does not exclude alternatives or compare with sibling tools, 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?

Adds behavioral details beyond annotations: explains data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. Annotations already indicate read-only, non-destructive, idempotent, open world – description complements perfectly.

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 detailed but efficient – front-loaded with examples and uses bullet-like structure. Slightly verbose but every sentence adds value; minor room for tighter organization.

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, so description fully explains returns (paired data, citation URIs). Covers types, data sources, sorting, and edge cases like off-calendar fiscal years. Complete for a comparison tool.

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

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

Schema has 100% coverage of both parameters, but description adds semantic context: values are tickers/CIKs for company type, drug names for drug type, and explains the different data pulled for each type.

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 explicitly states it performs side-by-side comparison of 2–5 companies or drugs, with clear query examples. It distinguishes from siblings like entity_profile by focusing on comparisons.

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 advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. Includes specific trigger phrases for the tool.

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

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

Adds significant behavioral context beyond annotations: decomposition into sub-questions, parallel execution, verbatim evidence with confidence/source/citation, explicit gaps array to avoid hallucination, and time expectation. Annotations already indicate read-only, idempotent, and non-destructive, which are consistent.

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 slightly long but every sentence earns its place. It's front-loaded with the main purpose, then details mechanics, usage guidance, and requirements. No wasted words, but could be trimmed slightly by combining some sentences.

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

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

For a complex tool with no output schema, the description is remarkably complete. It covers internal behavior (decomposition, parallel routing), output structure (findings packet with gaps), prerequisites (account, payment for depth), and timing. It even addresses hallucination prevention. No gaps remain.

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 clear descriptions for both parameters. The description adds value by explaining the meaning of depth levels ('quick=3, standard=5 (default), thorough=8 (paid plans)') and that question decomposition is central. Slight redundancy but overall helpful.

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 in ONE call' that decomposes questions into sub-questions, routes them to 3,744 tools in parallel, and returns a structured findings packet. It distinguishes itself from sibling ask_pipeworx by noting it's for broad/multi-part questions.

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 provides when-to-use guidance: 'Use for broad or multi-part questions... use ask_pipeworx for single lookups'. Also mentions account requirement, signup link, pricing for 'thorough' depth, and expected response time of 15-60s.

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

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

The description adds significant behavioral context beyond annotations: it explains that results are 'ready to call directly, no second schema lookup needed' and that it returns top-N relevant tools with schemas and examples. There is 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 concise, front-loaded with purpose and examples, and every sentence adds value. No unnecessary words.

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

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

Despite lacking an output schema, the description fully explains what is returned (names, descriptions, full schemas with examples). For a search/discovery tool, this is complete and self-contained.

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

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

Schema coverage is 100%, with all parameters described. The description repeats the alias information already in the schema and adds no new semantic detail beyond the examples 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 is for finding tools by describing data or task. It lists many specific domains (SEC filings, financials, FDA drugs, etc.) and explicitly distinguishes it from siblings by positioning it as a discovery-first meta-tool.

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

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

The description explicitly recommends calling this tool FIRST when exploring many tools and wanting to see the option set. It provides clear usage context but does not explicitly list when not to use it or mention 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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds context: fans out across multiple sources in one parallel call, soft-fails for patents, returns specific fields with 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?

Description is moderately long but well-structured: starts with example queries, then explains data sources and return fields. Every sentence adds value, though some repetition of schema info could be trimmed.

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 only 2 parameters and no output schema, the description is highly complete. It covers input options, data sources, return fields, limitations, fallback behavior, and alternative tools. No gaps for an agent to get stuck.

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. Description adds examples (e.g., 'AAPL', '0000320193') and explains that names are unsupported, pointing to resolve_entity. This provides useful context beyond the schema enums and 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?

Description clearly states it provides a full cross-source profile of US public companies, listing specific data types (filings, fundamentals, patents, news, LEI). It distinguishes itself from chaining single-pack lookups, making purpose unambiguous.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and mentions alternative tool (resolve_entity) for names. Also notes limitations like patents API sunset. Provides clear when-to-use and when-not-to.

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

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

Annotations already provide destructiveHint and idempotentHint. Description adds context about clearing sensitive data, enhancing transparency 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 concise sentences with no waste. First sentence states core purpose; second sentence adds use cases.

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

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

For a simple tool with one parameter, description covers purpose, usage context, and relationship to siblings. No gaps given lack of output schema.

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

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

Single parameter 'key' fully described in schema (100% coverage). Description doesn't add semantics beyond the schema's 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?

Clearly states 'delete a previously stored memory by key', specifying verb, resource, and distinguishing from siblings like 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?

Explicitly says when to use (stale context, task done, clear sensitive data) and pairs with related tools, providing 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?

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?

Adds behavioral details beyond annotations: comma-separated queries, type: prefixing, and info=true returning descriptions/URLs. No contradictions with readOnlyHint, openWorldHint, etc.

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 concise sentences, front-loaded with action, 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?

Covers core functionality, key parameters, and advanced options. Output schema exists so return values implicit. No missing critical info for a simple recommendation 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%, baseline 3. Description adds minimal extra: repeats enum values, one detail about info=true already in schema. No significant new semantic context.

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

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

Clear verb 'get', specific resource 'similar to X recommendations' from TasteDive, and distinguishes from diverse siblings like bet_research or ai_visibility_check.

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

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

Explicitly states how to narrow category via 'type' and enable extra info with 'info=true'. Provides context for use, though no explicit alternatives or exclusions.

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

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

Annotations already declare readOnlyHint 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?

The description discloses rate limiting (5 per identifier per day), that it's free and doesn't count against tool-call quota, and that the team reads digests daily. All annotations (readOnlyHint false, etc.) are consistent with this write operation, and the description adds valuable behavioral context beyond annotations.

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

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

The description is well-structured with a clear opening purpose sentence, followed by usage guidance and constraints. While it is somewhat long, every sentence adds value and there is no redundancy. It could be slightly tighter but is highly 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 no output schema and a simple feedback submission tool, the description covers every necessary aspect: purpose, usage, parameter guidance, and behavioral constraints. The context signals (3 params, 100% schema coverage) together with the description provide complete understanding for the 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 is 3. The description adds value by explaining the enum options in context and stating that context is optional. It also reinforces the message format. However, it does not add new information beyond what is in the schema, so a 4 is appropriate.

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

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

The description clearly states the tool's purpose: to provide feedback (bug, feature, data_gap, praise) to the Pipeworx team. It distinguishes itself from other tools by specifying its unique role, and there are no sibling tools with similar functionality.

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 the tool for each feedback type (bug, feature/data_gap, praise), provides formatting guidance (describe in terms of tools/packs, don't paste prompts), and mentions rate limits and quota implications. This is exemplary guidance.

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

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

Annotations already 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?

The description adds extensive behavioral context beyond the annotations (which already indicate safe, non-destructive reads). It details monotonicity checks, partition sum checks, semantic anchor (Jaccard similarity), partition filter (placeholder slugs), and fill check (realizable edge vs book depth). 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 structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the requirement. Every sentence provides necessary information; nothing is wasted. For a complex tool, this level of detail is appropriate and well-organized.

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

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

Given the tool's complexity, the absence of an output schema, and the richness of annotations, the description is remarkably complete. It covers both modes, edge cases (no args, placeholders, low similarity), and even cross-references another tool for fill risk. No gaps remain.

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?

Both parameters are described in the schema with summaries, and the description adds deeper meaning: explaining that `event` accepts slugs or URLs, `topic` is a seed question, and elaborating on how each mode works. Schema coverage is 100%, and the description adds significant value beyond schema.

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

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

The description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks, and distinguishes two modes (event and topic) with specific 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?

It explicitly requires one of `event` or `topic` and warns against calling with no args. It explains when to use each mode (event for specific market, topic for cross-event scanning) and mentions that cross-event catches patterns single-event misses. It references `polymarket_fill_risk` for custom sizing, but does not explicitly contrast with sibling tools like `polymarket_edges`.

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 readOnly, idempotent, non-destructive. Description adds retrieval behavior, listing mode, and scoping context without contradiction. The description coherently reinforces the read-only nature with examples of usage.

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

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

Three sentences with front-loaded core purpose. Each sentence adds value: function, usage examples, then scoping and pairing. No redundant or irrelevant 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?

Given simple input (one optional parameter) and no output schema, the description adequately explains input behavior and output types (value or list). Missing details on error handling (e.g., key not found) are minor for this straightforward 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 already covers the 'key' parameter with 100% description coverage (omit to list all). Description restates this but adds context about prior saves via 'remember'. Baseline is 3 due to high schema coverage; description provides slight extra context but does not significantly enhance parameter understanding.

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?

Purpose is clearly stated as retrieving a saved value or listing all keys, with explicit connection to 'remember' and 'forget' siblings. Examples like 'target ticker, address, prior research notes' provide concrete 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?

Explicitly states when to use (look up stored context) and when not to use (implicitly, for new data). Mentions omitting key to list all keys, and pairs with remember/forget for saving/deleting. Scoping details also guide appropriate usage.

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

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

Annotations 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 declare readOnlyHint and idempotentHint. Description adds multi-source fan-out behavior (SEC, GDELT→GNews fallback, USPTO), explains fallback logic when rate-limited and API sunset issue. 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 thorough but well-structured: starts with natural language queries, then technical explanation, return format, and sibling differentiation. Every sentence contributes value; could be slightly more concise but still efficient.

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

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

Given 100% schema coverage, moderate complexity (3 params, no nested objects), and no output schema, description covers all necessary aspects: purpose, parameters with examples, return format, limitations (patents soft-fail), and when to use sibling. Complete for safe, idempotent query 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 3 parameters. Description adds value by explaining since format (ISO or relative) with examples like '30d', and clarifies value as ticker or zero-padded CIK. Enhances 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?

Description clearly states it provides a change feed for a company over a time window, combining SEC filings, news, and patents. It starts with natural language examples and distinguishes itself from sibling entity_profile by specifying static profile use case.

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

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

Explicitly states when to use this tool vs entity_profile: 'Use entity_profile instead when you want the static profile'. Provides use cases like 'what's new with X' and typical monitoring window suggestions.

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

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

Adds value beyond annotations: persistence duration, scoping by identifier, key-value pair nature. No contradictions with annotations.

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

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

Three sentences, front-loaded purpose, clear structure, 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?

Covers purpose, usage, parameters, behavioral details, and pairing with other tools. No output schema needed.

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

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

Schema already describes key and value with examples; description adds context on typical key patterns and value types, enriching schema coverage.

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

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

Clearly states the tool saves data for reuse, specifies key-value storage, scoped by identifier, and distinguishes from siblings recall and forget.

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

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

Explicitly says to use when discovering something worth carrying forward, provides persistence details (persistent for auth, 24h for anonymous), but lacks explicit 'when not to use' statement.

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

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

Annotations already declare readOnly and idempotent; the description adds that each call cascades through several lookup endpoints internally and replaces manual lookups. It also details the return type per entity, giving agents clear behavioral expectations.

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

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

The description is a single paragraph but packs essential information with front-loaded purpose and usage. It is efficient but could benefit from slightly more structure (e.g., bullet points) for 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 no output schema, the description lists the pieces returned for each entity type (ticker, CIK, RxCUI, etc.) and mentions citation URIs. It is complete enough for an agent to understand the tool's output, though a structured specification would be more precise.

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

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

Schema coverage is 100% (both parameters described). The description adds value beyond the schema by providing input examples, explaining auto-disambiguation for company, and noting the citation URI. This is more than the baseline 3.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical identifier, with examples and explicit use case. It distinguishes from siblings by mentioning it replaces 2-3 manual lookups and is the first tool to use when 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?

The description explicitly says 'Use FIRST whenever you have a name but need an ID', and details supported types and returns. It implies when not to use but does not explicitly exclude scenarios or mention alternatives among the 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 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 indicate safe, read-only behavior. The description adds that the tool replaces 4-6 sequential calls and details the return format (verdict types, structured form, citation, percent delta). No contradictions with annotations. It could mention pagination or rate limits, but the current detail is solid.

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 trigger phrases and a clear purpose statement. While it is relatively long, every sentence adds value—scope, output format, and efficiency gains. Minor redundancy in explaining the domain twice, 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?

No output schema exists, so the description fully details the return types (verdict, structured form, citation, delta). It specifies scope limitations (company-financial claims only). For a single-parameter tool with high schema coverage and clear annotations, the description is complete and leaves no critical gaps.

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

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

With only one parameter and 100% schema coverage, the schema already describes the 'claim' field well. The description provides concrete examples ('Apple's FY2024 revenue was $400 billion'), adding clarity beyond the schema. This justifies a 4, as the description enriches the parameter 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 begins with explicit trigger phrases like 'Is it true that...' and 'fact check', immediately clarifying the tool's purpose. It specifies the domain (company-financial claims for US public companies via SEC EDGAR+XBRL), which distinguishes it from siblings like 'compare_entities' or 'entity_profile' that handle broader entity tasks.

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.' Trigger phrases help the agent recognize scenarios. However, it does not list sibling alternatives or state when not to use, though the domain restriction implies that non-financial claims should go elsewhere.

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