Pipedrive

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds valuable behavioral context: the default Workers AI model is free, probing Anthropic requires the user's own key with direct payment implications, and the return structure includes per-model score, confidence, signals, and raw_response. 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 three sentences, front-loaded with the core function, then details about models and output, and ends with use cases. Every sentence provides necessary information; no filler or redundancy.

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

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

Since there is no output schema, the description adequately explains the return format (per-model object plus combined view). It covers all parameter semantics via schema and adds the default behavior and use-case context. It could mention edge cases like rate limits or error handling, but given the moderate complexity and rich schema, it is sufficiently complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by explaining the default model and that the _apiKey parameter is only needed for Anthropic, clarifying the BYO-key cost model. It also emphasizes that omitting 'models' yields just workers-ai, which reinforces the schema but adds practical guidance.

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 specifies the tool's function: probing LLMs for knowledge about an entity and scoring visibility from 0-100. The verb 'Probe' and resource 'one or more LLMs' are specific, and the scope (business/brand/product/topic) is explicit. This clearly distinguishes it from siblings like scan_competitor_ai_presence, which focuses on competitors rather than general visibility.

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 names concrete use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also states the default model and when to pass an API key. However, it does not explicitly mention when not to use this tool or point to alternatives among the sibling tools, so it lacks an explicit exclusion or alternative recommendation.

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, providing a strong safety baseline. The description adds meaningful behavioral context: it routes to one of 5,344 tools, fills arguments automatically, and returns stable citation URIs. It also notes it works on every tier and is a single fast call. While it doesn't disclose failure modes or rate limits, the annotations plus added routing/citation behavior exceed the minimum bar.

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

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

The description is long but every sentence earns its place: it states preference, lists domains, explains routing, provides examples, covers alternatives, and notes tier compatibility. It is front-loaded with the critical 'PREFER OVER WEB SEARCH' directive and organized so the reader quickly grasps the tool's role and hierarchy relative to siblings. 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 broad question-answering tool that spans 5,344 tools and 1,393 sources, the description is remarkably complete. It covers what it does (routes, fills arguments, returns citations), when to use it (any factual question), when to step up (grounded or deep_research), and provides diverse examples. It also addresses potential ambiguity about web search and breaking news, ensuring the agent can confidently select and invoke the tool.

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

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

Schema description coverage is 100%: the 'question' parameter is fully described, including aliases. The description adds no syntactic details beyond the schema, but it does provide natural-language examples that illustrate the expected input format. With full schema coverage, the baseline of 3 is appropriate; the description contributes marginal value via examples but doesn't need to re-document parameters.

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: answering factual questions about current/historical data across many domains, routing to thousands of verified sources, and returning structured answers with citations. It uses specific verbs ('routes', 'fills', 'returns') and explicitly distinguishes itself from sibling tools (ask_pipeworx_grounded, deep_research), making its role 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 gives explicit guidance on when to use this tool: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. It provides concrete examples (e.g., 'current US unemployment rate', 'Apple's latest 10-K') and clear step-up alternatives ('use ask_pipeworx_grounded for hallucination-resistant single answer', 'deep_research for broad/multi-part questions'). This is textbook usage guidance.

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

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

Beyond the read-only, idempotent annotations, the description discloses its beta status, live candidate testing, and that it is a full working router rather than a fallback shim. The current state (no active candidate, retired on outcome evidence) provides transparency about its dynamic 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?

Four sentences deliver purpose, usage, current state, and reassurance. Some redundancy exists between 'no candidate active' and 'currently matches exactly,' but the structure is front-loaded and each sentence contributes necessary context.

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

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

The description covers purpose, usage guidelines, beta status, and relationship to stable ask_pipeworx. It omits a specific response format but references 'same response shape' as the sibling, which is acceptable given no output schema; slightly more detail would make it fully complete.

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

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

The input schema covers all 6 parameters with 100% description coverage, including aliases. The tool description mentions 'same arguments' as ask_pipeworx but adds no semantic detail beyond the schema, so it meets the baseline.

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

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

The description clearly states it is a beta version of ask_pipeworx, a universal router handling 5,344 tools with identical arguments and response shape. It distinguishes itself from the stable sibling by its experimental edge and live candidate routing, giving a specific verb (ask/router) and resource.

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

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

The description explicitly tells the agent to use it 'exactly like ask_pipeworx when you want the newest routing' and contrasts results with the stable router for merging decisions. It also notes the current inactive candidate, implying when to choose it for trying experimental routing improvements.

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

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

The description adds substantial behavioral detail beyond annotations: it specifies the success return shape and the refusal mechanism with specific refusal_reason values, explains the 'ONLY what the tool result contains' guarantee, and notes the extra LLM call cost. 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 compact yet information-dense, with a logical flow: what it does, return format, refusal format, usage guidance, and cost tradeoff. Every sentence adds value, and there is no redundancy or fluff.

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

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

Given the tool's complexity (routing across many sources, refusal handling, evidence extraction), the description fully covers return values, refusal reasons, use cases, and cost implications. Since there is no output schema, the description explicitly documents the return structure, making it complete for an agent to invoke and interpret 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 all aliases documented in the input schema. The description does not add parameter-level detail beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads. It explains the mechanism (routes through tools, extracts answer using only tool result) and distinguishes itself from the sibling ask_pipeworx by noting the same routing but grounded extraction.

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

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

Explicit guidance is given: use when answers will be quoted, cited, or acted on, and where facts must not be invented. It also names the alternative (ask_pipeworx) and gives a cost-based preference for casual lookups, providing both when-to-use and 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds rich behavior: low-confidence short-circuit to status:'low_confidence_match', suppression of analysis fields, handling of closed/dead markets, wide-spread market flagging, news fallback semantics, and resolution-rule risk (refund_50_50 etc.). This goes far beyond the annotations.

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

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

The description is long but exceptionally well-structured with ALL-CAPS section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, RESOLUTION-RULE RISK). Every sentence carries operational value, and the sections are logically ordered. It is appropriately sized for 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?

There is no output schema, so the description fully documents the response shape: result.market fields, result.analysis, result.evidence, market_match_confidence, market_match_alternatives, parent_event, news fallback fields, and safety/blocking behaviors. It covers edge cases like cancellation rules and illiquid spreads, making the tool safely invocable without external documentation.

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 baseline is 3. The description enhances the 'market' parameter by explaining resolver behavior (market_match_confidence, alternatives, suggestions) and the meaning of fan-out examples, adding value over the schema's basic format descriptions. However, it doesn't add detail for 'depth' or 'include_raw' beyond what the schema already 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 opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the tool resolves, classifies, fans out, and returns an evidence packet + comparison. It also lists concrete use cases ('Use for...') and provides classifiers, distinguishing it from generic sibling tools like 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 says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', giving clear context. It does not name specific sibling alternatives or explicit when-not-to-use conditions, so it lacks the exclusions needed for a 5.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. This fully discloses what the agent can expect beyond annotation flags.

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 flows logically from use case to provider. It is dense but every sentence adds value—no filler or repetition. The single-paragraph format is easy to scan while retaining all essential details.

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

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

For a tool with no output schema, the description adequately explains return format (paired data + citation URIs), sorting behavior, and both modes. It covers the key edge case of off-calendar fiscal years. Combined with annotations and schema, it provides full context for safe 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 already documents type and values well, but description enriches them with concrete examples (AAPL/MSFT, ozempic/mounjaro), entity type-specific meaning (company pulls 10-K metrics, drug pulls FAERS counts), and the 2–5 limit context. This clearly goes beyond the schema's basic field descriptions.

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

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

The description explicitly states the tool performs side-by-side comparisons of 2-5 companies or drugs in a single parallel call, with clear trigger phrases like 'X vs Y' and 'rank these companies'. It distinguishes itself from sequential single-pack lookups and sibling tools by emphasizing parallel 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?

It provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and contextual trigger phrases. It also states what each type (company/drug) does and notes it replaces 8–15 sequential lookups, making the choice obvious.

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

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

Annotations declare readOnly and idempotent, but description adds extensive behavioral detail: account requirements, parallel decomposition across 5,344 tools, findings packet structure with evidence/confidence/source/fetched_at, gaps[] and contradictions[], semantic excerpting, latency expectations, and the one-call multi-hop behavior. 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?

Description is dense but front-loaded with the critical account requirement, then proceeds logically through purpose, usage context, depth semantics, and output structure. Every sentence adds value, though the length is considerable; a slightly more compact structure could improve scannability.

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 carries full burden for return semantics. It thoroughly explains findings packet, gaps[], contradictions[], hop field, citation_uri, and timing. Covers prerequisites (account), alternatives, and edge cases (current news returning gaps[], making it complete for a complex tool.

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

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

Schema has 100% coverage, but description enhances meaning by elaborating depth values ('quick=3, standard=5... adds a gap-recovery hop... thorough=8 paid...') and clarifying that question can be broad/multi-part. This goes beyond the schema's descriptions and adds real decision value.

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

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

The description clearly states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources' in one call. It explicitly distinguishes from siblings by saying 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups and current news.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx' plus 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also explains depth variants for iterative follow-up, giving clear decision rules.

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=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds useful context: returns top-N relevant tools with schemas, each result ready to call directly, and advises using this first for option discovery. 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 front-loaded with a clear verb phrase and includes a compact list of domains plus return behavior. Every sentence adds value; no filler.

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

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

Covers purpose, usage context, return format (top-N, with schemas, ready to call), and priority advice. With strong annotations and full schema coverage, an agent has everything needed to select and invoke this 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 all params (including aliases) documented. The description adds no parameter-specific detail beyond 'describing the data or task,' so the baseline of 3 is appropriate since schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It distinguishes itself from sibling tools by being a meta-tool for discovery, with an explicit 'Call this FIRST' instruction and a scope list of domains.

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?

Description gives explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It hints at when not to use ('not just one answer') but doesn't name alternative tools explicitly.

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

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

Beyond the readOnly/idempotent annotations, the description discloses useful behavioral details: it fans out across multiple sources, returns specific fields, notes the USPTO PatentsView API sunset and soft-fail behavior, and explains the GDELT→GNews fallback. It doesn't cover all edge cases (e.g., not-found behavior), but it adds meaningful 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 long but information-dense. It front-loads the core purpose, then lists examples, usage guidance, and return structure. Each sentence adds value (examples, limitations, alternatives). Slightly verbose, but not wasted words.

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

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

With no output schema, the description carries the full burden of explaining returns, and it does so thoroughly: lists every component (CIK, recent filings with URI format, fundamentals with sort order, patents status, news fallback, LEI). It also clarifies input constraints. The description is complete enough for an agent to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving concrete examples ('Pass ticker "AAPL" or zero-padded CIK "0000320193"'), reinforcing that names are not supported, and noting the type enum only supports 'company.' This exceeds the schema's plain descriptions.

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

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

The description opens with a clear verb+resource: 'full cross-source profile of a US public company in ONE parallel call.' It lists numerous example queries and explicitly distinguishes itself from alternatives by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' This is unambiguous and differentiates from sibling tools like deep_research or compare_entities.

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

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

Usage guidance is explicit: it states when to prefer this tool ('when the user asks for a holistic view') and provides exclusions ('names not supported — use resolve_entity first if you only have a name'). This gives the agent clear decision criteria and names the alternative tool.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds the context of clearing sensitive data and the action of deletion, but doesn't disclose additional behavioral details beyond what annotations imply, such as whether deletion is reversible or the outcome of deleting a non-existent key.

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, with the core action in the first sentence and usage context in the second. It is concise and information-dense with no wasted words.

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

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

For a simple one-parameter delete tool, the description covers purpose, usage, and pairing with related tools. However, it doesn't mention the return value or what happens on failure, though this is minor given 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?

The input schema provides 100% coverage with a clear description of the 'key' parameter and an example. The description merely restates that deletion is 'by key' without adding new semantic information, so it meets the baseline.

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

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

The description clearly states 'Delete a previously stored memory by key', identifying the action, resource, and method. This distinguishes it from sibling tools like remember (store) and recall (retrieve).

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 when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier', providing clear usage scenarios. It also suggests pairing with remember and recall, though it doesn't explicitly state when not to use it or name alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint: false. The description adds valuable behavioral detail beyond these: it fetches the page, extracts specific elements, emits standard llms.txt markdown, and returns a single text blob. This goes beyond the annotations but does not discuss potential caveats like rate limits or network failures, which keeps it from a 5.

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 without being overly long. It front-loads the main action, then explains the process and output, and closes with use cases. Every sentence contributes value, though the 'Useful for' list could arguably be tightened. It is structured well for scanning.

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

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

For a tool with only 2 parameters, strong annotations, and no output schema, the description is highly complete. It explains the input (URL), the extraction logic, the output format, and the target location (site-root/llms.txt). None of this is required by the structured fields, so the description fully covers the tool's behavior and result.

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 fully documents both parameters (url and max_links) with descriptions and defaults. The description adds no additional parameter-specific meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It also outlines the process ('Fetches the page, extracts title/description/key links') and the output format, making the tool's purpose unmistakable. The unique resource (llms.txt) distinguishes it from sibling tools like 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?

The 'Useful for:' section provides explicit context for when to use the tool: client site indexing, personal project drafting, and competitor auditing. This gives clear usage guidance, though it does not explicitly mention alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is clear. The description adds value by stating the caller's scope and the default behavior of returning only active subscriptions, plus the specific fields returned, which exceeds annotation coverage.

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: the first states purpose and return fields, the second gives usage guidance. Every word earns its place, with no redundancy or fluff.

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

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

For a simple list tool with one optional parameter and no output schema, the description mentions the caller's scope, active-only default, and return fields. This is sufficiently complete to use the tool effectively, though it could optionally mention ordering or pagination.

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

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

The schema fully describes the only parameter (include_inactive) with a clear description and default value. The tool description does not add any additional parameter meaning, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'List' and the resource 'subscriptions', scoped to 'the caller's active subscriptions'. It also lists the return fields, making it distinct from sibling tools 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?

The description provides explicit use cases: 'review what you're monitoring before adding more' and 'to find an id to cancel'. While it doesn't explicitly name alternatives, it implies when to use this tool relative to subscribe/unsubscribe, giving clear contextual guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds what data is returned (title, value, stage, probability, owner, contacts, timeline), which is useful behavioral context. 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?

One sentence, front-loaded with the action and resource, followed by concise list of return fields. No filler.

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

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

Output schema is present, so return values are covered. Description provides a good overview, annotations cover safety and idempotency, and params are fully documented. Enough for an agent to invoke correctly.

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

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

Schema covers both parameters with descriptions (id and _apiKey), so description doesn't need to add more. Description's 'by ID' is redundant with 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 uses specific verb 'Get' with resource 'specific deal (by ID)' and lists returned fields. Clearly distinguishes from sibling tools like pipedrive_list_deals (list) and pipedrive_get_person (different entity).

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

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

States the intended use case: fetch complete details for a specific deal using its ID. However, it does not explicitly mention when not to use it vs alternatives like search or list, so only implied.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds value by disclosing the response contents (emails, phones, organization, associated deals, custom fields), giving the agent a clear expectation of what the tool returns without needing to inspect the output schema.

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 compact sentences, front-loaded with the core action and immediately followed by the return payload. Every word contributes; no filler or redundancy.

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

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

For a simple GET-by-ID tool, the description is fully adequate: annotations declare safety, schema fully documents parameters, output schema presumably details the response shape, and the description adds the human-readable summary of returned fields.

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 both id and _apiKey already documented. The description reinforces the 'by ID' usage but adds no new meaning beyond 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 the tool fetches full contact details by ID, listing the returned fields (name, emails, phones, organization, deals, custom fields). This specific verb+resource+ID scope distinguishes it from siblings like pipedrive_list_persons or pipedrive_get_deal.

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 phrase 'by ID' implies the tool is for retrieving a single person's full record when you have the ID, contrasting with list/search tools. While no explicit alternatives are named, the context is clear enough for an agent to select it appropriately.

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 useful context beyond annotations by specifying the returned fields (deal IDs, titles, values, stages, owners), which helps the agent understand the output. 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 two sentences: front-loaded with the action and resource, then a summary of returned data, then an explicit pointer to a sibling tool. Every sentence earns its place with no filler.

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

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

Given the tool's low complexity, full schema coverage, rich annotations, and an output schema, the description provides sufficient context. It communicates the tool's purpose, key return fields, and directs to the appropriate alternative for deeper detail.

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

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

The input schema already covers 100% of the parameter descriptions (limit, start, status, _apiKey), so the description does not need to explain them. It adds no additional parameter-specific semantics 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 uses a specific verb 'View all deals' and identifies the resource 'your pipeline.' It clearly distinguishes from siblings like pipedrive_get_deal and pipedrive_list_persons by stating it returns deal IDs, titles, values, stages, and owners, and it explicitly points to pipedrive_get_deal for full 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 guides the agent to use pipedrive_get_deal for full details on a specific deal, which provides a clear alternative and implies when not to use this list tool. This satisfies the need for when/when-not/alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds value by specifying the returned data (emails, phones, associated organizations/deals), which helps the agent set expectations 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 two sentences long, with the primary action stated in the first sentence and return fields in the second. Every word earns its place; there is no fluff or redundancy.

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

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

Given the tool's low complexity, strong annotations (read-only, idempotent, destructive=false), and the presence of an output schema, the description fully covers the necessary context. It even previews the return fields, making the tool self-sufficient for an agent.

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

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

The input schema has 100% description coverage for all three parameters (limit, start, _apiKey), so the schema fully explains parameter meaning. The description adds no additional parameter semantics 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 uses a specific verb ('View all contacts') and identifies the resource (contacts in CRM), clearly distinguishing it from siblings like pipedrive_get_person (specific person) and pipedrive_list_deals (deals). It also lists expected output fields, making the tool's purpose unambiguous.

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

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

The description provides clear context for when to use this tool: to view all contacts in the CRM. It does not explicitly name alternatives or exclusions, but the sibling tool names and the description's focus make the usage scenario obvious.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is well-covered. The description adds that results include IDs and basic info, but does not disclose additional behaviors like pagination, default limits, or rate limits. This is acceptable for a simple read-only search tool but not particularly rich.

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

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

The description is a single, efficient sentence that front-loads the core purpose and return value. No unnecessary 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?

For a simple search tool with full schema coverage, rich annotations, and an output schema, the description covers the essential purpose and return information. The schema handles parameter details, and annotations handle safety, making this complete.

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

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

The input schema provides full descriptions for all four parameters, so the description does not need to compensate. The description adds no extra parameter semantics beyond what the schema already provides, so a 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 clearly states the tool performs a keyword search across multiple Pipedrive entity types (deals, contacts, organizations, products, files) and returns records with IDs and basic info. This distinguishes it from sibling get/list tools which operate on single entities or list all.

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 makes it clear that this is for keyword-based searching across specified entity types, implying it is appropriate when you need to find records by term rather than fetching by known ID or listing all. However, it does not explicitly state when not to use it or mention alternatives like pipedrive_get_deal or pipedrive_list_deals.

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?

All annotations are false, so the description carries the full burden of behavioral disclosure. It discloses the rate limit ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and impact ('signal directly affects roadmap', 'team reads digests daily'). It also tells the user how to phrase feedback appropriately. 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 compact and well-structured: first sentence states the core purpose, second gives usage conditions, third provides content guidance, fourth explains impact, and fifth covers rate/cost. Every sentence adds necessary value, with no redundancy or filler. It is front-loaded with the most important 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?

Without an output schema, the description need not explain return values. It fully covers the tool's purpose, usage scenarios, message formatting rules, rate limits, and cost implications. The optional context parameter is well-documented in the schema, and the description's instruction to reference tools/packs implies the use of context fields. For a feedback tool, this is complete and self-sufficient.

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

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

The schema covers all three parameters with meaningful descriptions, so the baseline is 3. The description adds substantial semantic guidance: it tells the user to frame feedback in terms of Pipeworx tools/packs (relevant to the message parameter) and clarifies when each type should be chosen (bug/feature/data_gap/praise). This goes beyond the schema's simple enum descriptions, enriching 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?

The description clearly states the tool's action ('Tell the Pipeworx team something is broken, missing, or needs to exist') and the resource (Pipeworx team). It explicitly enumerates the use cases (bug, feature/data_gap, praise), making it distinct from any sibling tool. No other sibling offers a feedback channel, so there is no 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 when-to-use conditions: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also includes a what-not-to-do instruction ('don't paste the end-user's prompt') and explains the intended format ('describe the issue in terms of Pipeworx tools/packs'). This gives clear guidance beyond the schema.

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

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

Beyond the annotations (read-only, idempotent, etc.), the description reveals meaningful behavioral traits: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This adds context about data source, privacy, and caching behavior that annotations do not provide.

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

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

The description is well-structured and front-loaded with a clear hook ('What other AI agents are calling on Pipeworx right now'), followed by output details, enumerated use cases, and a concise behavioral note. Every sentence adds value without unnecessary verbosity.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers the output contents, data source, caching, and privacy. It provides enough context for an agent to select and invoke the tool correctly, and the annotations fill in the safety profile.

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

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

The schema already has 100% parameter description coverage, including guidance that 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' The tool description reinforces the window options but adds little semantic value beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' It uses specific verbs and identifies the resource (Pipeworx trends), which distinguishes it from sibling tools 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 provides explicit 'Useful for' scenarios: discovering hot data sources, confirming canonical tool choice, and checking use-case alignment. This is clear context, but it does not explicitly name alternatives or state when not to use the tool, so it stops short of a 5.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses many behavioral traits: no-args defaults, the semantic anchor with a Jaccard threshold, the partition filter with placeholder fraction, the fill check against live CLOB depth, and the exact conditions that produce a signal. It also reveals internal logic (e.g., >3pp deviations emit BUY/SELL EVERY LEG) and result 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 long but information-dense, with clear section delimiters (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It front-loads the primary purpose and no-args behavior, then details each mode. Every sentence adds value—there is no filler or repetition. The structured format makes it easy to scan for key behavior.

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

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

Given no output schema, the description fully explains the response structure (opportunities[], partition_check{}, fill_check details) and provides edge-case behaviors (skipped_low_similarity, placeholders_filtered). It covers all invocation modes, prerequisites, and failure conditions. The description is self-contained and leaves no major gaps for the agent to infer.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning beyond the schema. It explains the difference between event and topic modes, gives example slugs, describes the behavior when no args are passed, and clarifies that full Polymarket URLs are accepted. It also explains the consequences of each parameter choice (e.g., single-event vs cross-event scans), greatly enhancing 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 states a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool from siblings by detailing three modes (no-args trending_scan, event, topic) and explicitly references related tools like polymarket_fill_risk for custom sizing.

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

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

The description provides explicit when-to-use guidance: call with no args for trending scan, pass 'event' for a specific market, or 'topic' for cross-event scanning. It also gives concrete examples (e.g., 'fed-decision-may-2026') and warns when not to trade (realizable_edge_pp ≤ 0). Alternatives are mentioned ('For custom sizing use polymarket_fill_risk'), offering clear 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 mark the tool as read-only, open-world, idempotent, and non-destructive. The description goes far beyond annotations by disclosing caching behavior ('Cached 1h at the KV level keyed on all knobs'), response structure, diagnostics for empty segments, filter mechanics (tradeable-edge knobs), and the 24h-move warning. It also highlights the rare-by-design nature of concentrated longshots. No contradictions with annotations.

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

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

The description is long but information-dense. It is well-structured with labeled sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and front-loads the core purpose. Every sentence adds value, though it could be tightened slightly without losing essential details.

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

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

Since there is no output schema, the description fully compensates by documenting the response structure (by_segment, fed_candidates, _diagnostics) and per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.). It also covers edge cases like empty segments, filter skips, and caching, making it comprehensive for a complex, multi-segment 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?

All 9 parameters have schema descriptions (100% coverage), so the baseline is 3. The description adds meaning by grouping knobs (e.g., 'TRADEABLE-EDGE KNOBS') and explaining how they interact with segments, such as min_partition_leg_kelly applying to per-leg Kelly inside partitions. While not exhaustive per-parameter detail, it provides valuable 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 function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further differentiates from siblings by detailing three distinct model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), which aligns with the 'what should I bet on today' use case. This is a specific verb+resource+scope statement that stands apart from sibling tools.

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

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

The description provides a clear usage context: it is built for agents to discover betting opportunities without paging through hundreds of markets. It also explains the fed_candidates exclusion and why (unreliable signal without paid data). However, it does not explicitly state when NOT to use this tool or name alternative tools for specific scenarios, which prevents a 5.

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

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

Annotations already cover read-only and non-destructive hints, but the description adds significant behavioral context: snapshot data is written only on cache-miss, gaps reflect days no scan occurred, history is limited by a 60-day TTL, and decay is computed from daily closes (not intraday). This goes well beyond annotations.

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

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

The description is dense but well-structured, with labeled sections (Args, RESPONSE, LIMITS). Every sentence adds value, especially the detailed response format which compensates for the missing output schema. It is front-loaded with purpose and use case.

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

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

Given the lack of an output schema and the tool's complexity, the description is remarkably complete: it explains the response structure, data semantics, and limitations (TTL, snapshot gaps, decay calculation). It leaves no critical gap for an agent to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds slight context by calling 'window' a 'snapshot family' and clarifying defaults, but it largely restates the schema. No substantial new parameter meaning is provided.

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

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

The description clearly states a specific purpose: 'Edge persistence and decay telemetry' and answers a precise question ('how long has this edge existed and is it shrinking?'). It distinguishes from sibling tools by focusing on historical persistence versus likely current-edge tools like polymarket_edges.

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

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

The description provides clear context for when to use this tool (when edge age/decay matters) and even illustrates the use case ('a 3-week-old wide edge is wide for a reason nobody is willing to take'). However, it does not explicitly name alternatives or state when NOT to use it, which would make it a 5.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral detail beyond this: it walks the order book ladder, returns specific metrics, exposes partial fill risks, and warns about forced_directional_risk. This is exactly the kind of context that helps an agent anticipate outcomes without placing a trade.

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

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

Though long, the description is densely packed and front-loaded with the core purpose. It uses a clear structure: purpose sentence, REQUIRES note, then explicit mode breakdowns with return values. Every sentence adds essential information; there is no fluff or repetition, making it appropriately sized for 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?

Given the tool's complexity (two modes, 4 params, no output schema), the description fully covers inputs, outputs, and failure modes. It enumerates return fields for both modes, explains edge-case risks like partial fills and thin legs, and gives practical usage context. Nothing essential is missing for an agent to invoke and interpret 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 descriptions cover all four parameters (100%), but the description adds valuable semantics beyond the schema: size_usd is clarified as 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional' in basket mode, and side gets mode-specific default logic. This clearly elevates understanding of parameter 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 opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes and explicitly ties it to sibling tools (polymarket_arbitrage, polymarket_edges), making its purpose unambiguous.

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

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

The description explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also implies exclusions by noting that theoretical overround on thin books is not capturable, providing clear context for when alternative tools would be inappropriate.

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

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

Despite annotations already declaring readOnly, openWorld, idempotent, and non-destructive, the description adds substantial operational detail: compatibility_warning triggers, temporal_alignment semantics, skipped_cross_type/subtype counters, and an explicit caution that most macro shortcuts currently return warnings. This far exceeds the annotation baseline.

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

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

The description is lengthy but well-structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. Each section earns its place given the tool's complexity, though a few details could be trimmed without losing 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?

With no output schema, the description must explain return values and edge cases, and it does: it describes leg-by-leg prices, matched spread[], compatibility_warning cases, temporal_alignment, and skipped counters. It provides a comprehensive picture of the tool's behavior in diverse scenarios.

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 coverage, the baseline is 3, but the description meaningfully enriches the parameter semantics by explaining the two modes, how explicit tickers override topic mappings, and providing concrete examples like 'fed' and 'fed-decision-in-june-825'. This adds essential usage logic not present 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 opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly states a specific function and resource. It further distinguishes itself from potential siblings by emphasizing the cross-venue comparison and the two operational modes.

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 clearly explains when to use the tool (cross-venue spread for matching questions) and describes the two modes (topic shortcuts vs explicit tickers). It also warns about when the tool is not reliable (incompatible bet shapes, misaligned temporal periods, pre-mapped topics often not tradeable), but it does not explicitly name alternative 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?

The description adds meaningful context beyond the readOnlyHint and idempotentHint annotations by explaining that memory is scoped to an identifier (anonymous IP, BYO key hash, or account ID). This clarifies the memory model and isolation behavior. 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 three sentences, front-loaded with the primary function, then usage context, then scoping. Every sentence adds value without redundancy, making it both concise and well-structured.

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

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

For a simple one-parameter memory retrieval tool with strong annotations and schema coverage, the description covers purpose, usage, scoping, and sibling relationship. No output schema is needed, and the description is complete for effective use.

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

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

The schema already fully documents the optional 'key' parameter with the same omit-to-list behavior, and the description's mention of omitting the key is redundant. The description adds examples of typical key values but no new parameter semantics, so it stays at the baseline given 100% schema coverage.

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

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

The description clearly states the tool's function: retrieving a previously saved value via remember, or listing all keys when the key argument is omitted. It uses a specific verb ('Retrieve') and distinguishes itself from sibling tools like remember and forget by explicitly pairing with them.

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

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

It explicitly says to use this tool for looking up previously stored agent context without re-deriving it, and mentions pairing with remember (save) and forget (delete). However, it does not list explicit exclusions or alternative tools for external lookups, so it is clear but not fully exhaustive.

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 explicitly documents a state-changing behavior: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This directly contradicts the readOnlyHint=true annotation, which declares the operation as read-only. The description is transparent, but because it conflicts with the structured safety hint, it merits a score of 1 per the contradiction rule.

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 with zero fluff. It front-loads the core purpose, then packs in return fields, filter usage, mark_read side effect, polling guidance, and an alternative endpoint. Every sentence earns its place, and the structure is easy to scan.

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

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

For a read-only list tool, the description covers the essential operational details: response payload fields, filter mechanisms, the mark_read side effect, and polling suitability. It omits pagination specifics, but the limit parameter in the schema covers that gap. Overall, it is sufficiently complete to invoke the tool correctly, though a note on unread_only behavior would have been nice (already in schema).

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful value beyond the schema by giving an example filter value ('sec_8k'), explaining the semantic effect of mark_read (stateful flagging), and outlining what each returned event contains. This goes beyond simple field definitions and compensates for the lack of an output schema.

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

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

The description opens with the specific verb+resource combination 'Pull fired events from your subscription feed,' and immediately clarifies the tool's scope (recent alerts, written by the evaluator). This clearly distinguishes it from siblings like list_subscriptions or recent_changes, which manage subscriptions or track changes rather than reading fired alerts.

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

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

The description provides practical usage context: 'Polls work fine' tells the agent that repeated polling is acceptable, and the alternative GET endpoint indicates when scripts/dashboards might prefer a different route. It does not explicitly name sibling tools or give exclusions, but the context is strong enough to imply when this tool should be used.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses multi-source fan-out, GDELT→GNews fallback, USPTO soft-fail due to API sunset, and the structure of the response. This adds significant behavioral context not present in the annotations.

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

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

The description is dense and information-rich, starting with practical query examples that quickly convey purpose. While it is longer than average, each clause earns its place by covering sources, fallback, parameter syntax, and return structure without redundancy.

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

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

Given the tool's complexity (three sources, fallback logic, API deprecation), the description covers all essential aspects: input format, return structure, limitations, and an explicit alternative. Even without an output schema, the description fully compensates by describing the return shape.

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 repeats the parameter details already in the schema (e.g., ISO date/relative shorthand for `since`, ticker/CIK for `value`) without adding new semantic information 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 uses a specific verb ('change feed') and resource ('for a company'), and clearly defines its scope with natural language examples ('What's new with X'). It explicitly distinguishes itself from the sibling tool entity_profile, fulfilling the differentiation requirement.

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

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

The description provides explicit usage context with query examples and specifies when to use an alternative ('Use entity_profile instead when you want the static profile...'). It also clarifies the fallback behavior among data sources, giving clear guidance on operational 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 only indicate idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds valuable behavioral context beyond these hints: storage as a key-value pair scoped by identifier, persistent vs 24-hour TTL based on auth status, and the lifecycle with recall and forget. 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: it opens with purpose, gives usage context, then details scoping and persistence, and ends with sibling relationships. Every sentence adds information and there is no redundancy or fluff. It is appropriately sized for a simple 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?

For a simple key-value save tool, the description covers all relevant aspects: storage model, scoping, TTL, authentication differences, and how it links to recall/forget. No output schema is present, but the description makes clear the saved data is not returned and must be retrieved via recall. The tool is fully understood from the description.

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

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

Schema coverage is 100% with both key and value having descriptive names and examples. The description reinforces the key-value concept and gives examples, but it does not add meaning beyond what the schema already provides. Baseline 3 is appropriate because the schema carries the semantic weight.

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

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

The description opens with a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly distinguishes the tool from siblings by explicitly pairing it with 'recall' to retrieve and 'forget' to delete, and provides concrete use-case examples like 'resolved ticker' and 'user preference.'

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 when to use the tool ('Use when you discover something worth carrying forward') and gives examples of appropriate content. It also names alternatives ('Pair with recall to retrieve later, forget to delete') and explains persistence differences for authenticated vs anonymous sessions, giving the agent clear decision criteria.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds substantial context: each call cascades through multiple lookup endpoints, auto-disambiguates inputs, and returns specific citation URIs. This goes well beyond the structured annotations.

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

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

The description is dense but well-structured, with examples front-loaded and SUPPORTED TYPES clearly delineated. Every sentence contributes useful information, and length is appropriate for 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 explain return values. It does so thoroughly for both entity types, including quote URIs. It also covers disambiguation behavior and the value of replacing manual lookups, making the tool self-explanatory.

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 parameters are already documented. The description adds value by detailing input variations (ticker, CIK, or name for company; brand or generic for drug) and the exact return payloads (e.g., 10-digit CIK, RxCUI), which enriches the schema meaning.

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 name to a canonical identifier, with specific verb ('resolve'), resource ('user-spoken NAME to canonical/official identifier'), and concrete examples. It distinguishes from siblings by being the entry point for ID lookup, 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 gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' This is clear context for when to use. However, it does not explicitly mention when not to use or name alternative tools for cases where an ID is already available.

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 beyond annotations by revealing that it calls ai_visibility_check per entity, ranks by score, and returns specific fields (score, confidence, signal density). It also notes the ranking behavior. While it doesn't mention potential cost or latency of multiple probes, the given behavior is well disclosed.

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

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

Three sentences, front-loaded with the main action, followed by the mechanism, use case, and output. Every sentence adds value, no fluff.

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

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

Without an output schema, the description appropriately describes the return format (ranked list with score/confidence/signal density). It also covers the probe delegation. Minor gap: no mention of model defaults or API key requirements, but those are in the schema, so not a major omission.

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

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

Schema coverage is 100%, so the description carries no extra param details. The description's mention of entities and subject/competitor roles is already in the schema. It meets the baseline expectation without adding beyond schema.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the mechanism (probes with ai_visibility_check), the output (ranked list), and differentiates from the sibling single-entity check tool 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?

It provides a concrete use case ('competitive AI-marketing audits') and implies a multi-entity scenario where ai_visibility_check would be used for a single entity. However, it does not explicitly state when not to use it or name alternative tools, stopping short of a full 5.

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

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

The description discloses rich behavioral traits beyond annotations: it fans out to multiple sources, can take 5-30s on first bundlephobia measurement, degrades gracefully on partial failures, and lists the `sources_failed` field. It also details the return structure, which is especially valuable given no output schema. No contradiction with readOnlyHint/idempotentHint.

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

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

The description is dense but every sentence earns its place. It front-loads the core purpose, then provides usage, return fields, limitations, and failure behavior. It is well-structured with a natural flow and no redundant fluff, given the tool's composite nature.

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

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

With no output schema, the description compensates by listing the summary fields and other return components. It covers when to use, what data is aggregated, ecosystem limitations, latency expectations, and graceful degradation. This is complete enough for an agent to correctly invoke and interpret the tool.

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

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

Schema description coverage is 100%: both `package` and `version` have clear descriptions including scoped packages and default-to-latest. The tool description adds little beyond the schema; it reinforces the npm-only constraint but does not offer new parameter-level detail. Baseline 3 applies.

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

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

The description clearly states the tool's purpose: a composite check for evaluating whether to add an npm package to a project, combining deps.dev and bundlephobia data. It uses a specific verb ('scan') and resource ('dependency'), and is easily distinguished from sibling tools like scan_competitor_ai_presence or bet_research.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives an exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', clarifying when not to use this tool.

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

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

The description goes well beyond the read-only annotation by disclosing the underlying mechanics: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and the 200K char cap with truncation flagging. It also explains that passages carry character offsets for verification, adding meaningful behavioral context not present in 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 three dense sentences with zero redundancy. It front-loads the core action, then efficiently adds use cases, sibling pairing, algorithmic details, and constraints without wasted words.

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

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

Despite lacking an output schema, the description fully specifies the return content (passages, character offsets, similarity scores) and key constraints (200K char cap, truncation flag). It also situates the tool within a broader workflow (fetch with gateway, ground over passages), making it self-sufficient for an agent to understand and invoke correctly.

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

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

Schema description coverage is 100%, setting a baseline of 3. The description adds value by giving concrete, real-world examples for both `text` (e.g., SEC 10-K body, article) and `query` (e.g., 'supply-chain risk'), which helps the agent understand how to populate these fields. It does not add detail for `limit`, but the schema already defines it clearly.

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

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

The description clearly states a specific verb+resource: 'Semantic search INSIDE a fetched record,' and clarifies the output (top-N passages with offsets and similarity scores). It distinguishes itself from siblings by explicitly pairing with ask_pipeworx_grounded, emphasizing that this tool retrieves passages rather than processing the whole document.

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

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

Explicit when-to-use guidance appears: 'Use when the record is too big to cram into the prompt — search_within saves context...' It also names an alternative (ask_pipeworx_grounded) and explains the intended pairing, providing clear context for when this tool is the better choice.

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 useful behavioral details beyond the annotations: requires OAuth, anonymous/BYO cannot persist, SMS verification and 10/day cap, and the always-on feed. There is no contradiction with the readOnlyHint/idempotentHint annotations, and the write behavior is implicitly clear.

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 and front-loaded with the primary purpose and return value. It is not perfectly concise due to some repeated schema details (e.g., delivery options), but every sentence contributes meaningful 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 covers the main subscription types, delivery channels, account requirements, and return value, which is adequate for a complex tool with no output schema. It omits explicit mention of patent_grant and clinical_trial types, but these are fully documented in the 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?

With 100% schema description coverage, the baseline is 3, but the description adds concrete examples for type-specific params (e.g., sec_8k items meaning officer change, polymarket_edge topic) and explains delivery semantics, adding value beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It uses a specific verb ('Create') and resource, and is easily distinguished from sibling tools like list_subscriptions 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?

The description gives clear context for when to use the tool by stating the prerequisite of a Pipeworx OAuth account and noting that the feed is always on and can be pulled via recent_alerts. It does not explicitly contrast with list_subscriptions/unsubscribe, but the use case is well implied.

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

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

Annotations already declare the tool read-only and non-destructive. The description adds meaningful context about the output (category-bucketed examples, live catalog) but does not discuss pagination or rate limits. Since annotations cover the safety profile, the description's extra detail is valuable and sufficient.

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

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

The description is longer than average but every sentence adds useful information, from natural language triggers to output structure and usage timing. It is front-loaded with example queries and remains focused without fluff.

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

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

Given the tool's simple schema (1 optional param) and strong annotations, the description covers what it does, what it returns, when to use it, and how to parameterize it. Even without an output schema, it clearly specifies the return concept (category-bucketed questions with tool+argument shape).

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

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

The schema only describes 'topic' as an optional string with an enum-like list, but the description adds that omitting it yields a cross-category spread and gives concrete examples ('finance', 'pharma', 'betting'). This clarifies the parameter's effect 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 identifies the tool as the onboarding entry point for discovering what questions to ask, returning category-bucketed example questions with the exact tool and argument shape. This distinguishes it from the sibling 'discover_tools' by focusing on question suggestions rather than tool discovery.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call it with or without the 'topic' parameter. It also references meta-tools as things to learn to call, providing clear timing and 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 meaningfully supplements the annotations by disclosing that ownership is enforced, the row is deactivated rather than deleted, and historical events remain available via recent_alerts. This adds important behavioral context beyond the readOnly/destructive/idempotent hints and does not contradict them.

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

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

Two sentences, front-loaded with the core action, and every sentence adds distinct value: what it does, a constraint, and a side effect with a pointer to the relevant sibling tool. 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 cancellation tool with one parameter and no output schema, the description explains the outcome (deactivated, not deleted) and how to retrieve historical events (recent_alerts). This is sufficient context for an agent to invoke it correctly.

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

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

The schema already documents the 'id' parameter fully (subscription id returned by subscribe). The description adds no new parameter semantics beyond 'by id', so the baseline score of 3 applies due to high schema coverage.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific verb and resource, and distinguishes it from siblings like 'subscribe' and 'list_subscriptions'. It also adds unique behavior (ownership enforcement, deactivation) that clarifies its scope.

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

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

The description provides clear context for when to use the tool (you own the subscription) and mentions the alternative 'recent_alerts' to still access historical events after cancellation. It does not explicitly list 'when not to use', but the ownership rule and deactivation behavior effectively guide 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds rich behavioral detail: the two-path verification (structured vs. grounded), the tolerance_pct override mechanism, return of a verdict with citation and reasoning, and the 'verbatim evidence' guarantee. This gives the agent a clear mental model of how results are produced and judged.

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

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

The description is longer than average but well-structured: it opens with trigger phrases, states the core function, then details routing and return behavior. Every sentence adds value (e.g., the efficiency claim). It could be slightly tightened, but it remains focused 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?

Given the tool's moderate complexity (2 parameters, no output schema), the description covers all necessary context: when to use, what inputs are expected, how routing works, what the response contains (verdict, actual value, citation, reasoning), and special tolerance handling. It is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

The schema already documents both parameters with 100% coverage, but the description goes further by giving concrete claim examples for the 'claim' parameter and explaining exactly how tolerance_pct overrides the implied tolerance and caps at 5 by default. This adds operational meaning beyond the schema's basic field descriptions.

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

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

The description clearly states the tool performs 'natural-language claim verification against authoritative sources' and provides explicit trigger phrases ('fact check', 'verify the claim that…'). It distinguishes itself by detailing a unique SEC EDGAR/XBRL fast path for company financial claims and a general grounded pipeline for all other claims, which separates it from sibling tools like ask_pipeworx or deep_research.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' which is strong when-to-use guidance. It also explains the routing logic (financial vs. non-financial claims) and notes that it replaces 4–6 sequential calls, implying efficiency. However, it does not name specific alternative tools or provide explicit 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.