Dblp

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds beyond: default model (Workers AI Llama-3.3-70b free), need for _apiKey for Anthropic (BYO key, you pay), and return structure. No contradictions. Could mention failure modes, but good overall.

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

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

The description is a single paragraph with clear, purposeful sentences. It front-loads the main action and then details parameters and use cases. No wasted words 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?

Despite no output schema, the description explains the return structure: per-model {score, confidence, signals, raw_response} and combined view. It covers all parameters and their roles. Could add more on error handling, but sufficient for a probing 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%, baseline 3. The description adds meaning: explains default model for 'models' parameter, clarifies _apiKey is for Anthropic and passed through, and that 'context' disambiguates. It provides context beyond schema descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100). It uses specific verbs and resources, and distinguishes its purpose from siblings by focusing on AI visibility scoring.

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: AI-marketing audits, pre-launch brand checks, competitive monitoring. It does not explicitly state when not to use or name alternatives, but the context is clear.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive nature. The description adds valuable context: routes to 3,899 tools across 932 sources, returns structured answers with stable citation URIs, and fills arguments automatically.

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

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

The description is somewhat lengthy but well-organized with front-loaded purpose and usage guidance. Examples and sibling comparisons are useful. Slight reduction possible 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?

For a complex tool with many siblings and no output schema, the description covers purpose, usage, behavioral traits, and alternatives comprehensively. It leaves no major gaps for an agent invoking this tool.

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

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

Schema description coverage is 100%, so the description adds little beyond the alias list and a generic 'natural language' hint. Baseline 3 is appropriate since the 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 function: routing questions to a large set of verified sources for authoritative structured data with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each.

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

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

Explicitly recommends preferring this over web search for factual questions, provides concrete examples, and clearly states when to step up to alternatives (e.g., ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad queries). Also notes it works on every tier.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context: it describes the routing process, extraction method ('using ONLY what the tool result contains'), and detailed return structure including refusal reasons. No contradictions with annotations.

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

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

The description is well-structured with a clear front-loaded purpose, followed by process, return format, usage guidance, and cost trade-off. Every sentence adds value without redundancy. It is appropriately detailed 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 has no output schema, the description fully compensates by describing the return fields (answer, evidence, confidence, etc.) and refusal reasons. It also explains the workflow and cost, making the tool's behavior fully transparent to the agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces that the parameter is a natural language question and lists aliases, adding clarity beyond the schema's individual descriptions. It does not add new parameter constraints or formats, but the integration with the overall purpose is helpful.

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

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

The description explicitly states 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes from the sibling 'ask_pipeworx' by noting it extracts answers only from tool results and is for high-stakes use cases. The verb 'ask' and resource 'Pipeworx' are clear.

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

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

The description provides explicit guidance on when to use (when answers will be quoted, cited, or acted on, and the agent must not invent facts) and when not to use (prefer 'ask_pipeworx for casual lookups' due to extra LLM cost). It names the alternative directly.

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 non-destructive. The description adds extensive behavioral details: market resolution, fan-out logic, response shapes, safety mechanisms (low-confidence short-circuits, closed market handling, wide spread warnings), resolution-rule risk, and parent event extraction. 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 front-loaded with key purpose and use cases. It contains valuable detail but could be more structured, e.g., separating example fan-outs or edge cases into bullet points. Every sentence earns its place.

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

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

Given the tool's complexity (multi-step fan-out, classification, safety checks, return shapes), the description is remarkably complete. It covers resolution confidence, parent events, news fallback, closed markets, illiquidity, and cancellation rules. No output schema exists, so the description fully accounts for return value semantics.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds significant context beyond schema, such as 'quick = 2-3 evidence sources, thorough = full fan-out' and 'include_raw' behavior. The market parameter examples clarify acceptable inputs.

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 ('Research') and resource ('Polymarket bet') and clearly states it pulls Pipeworx data in one call. It distinguishes from sibling tools like polymarket_edges by specifying use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'.

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

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

Explicitly states when to use the tool with three example use cases. Does not explicitly mention when not to use or contrast with alternatives, but the use cases imply differentiation from siblings. Could be improved by stating exclusions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by detailing behavioral traits: it returns paired data with citation URIs, sorts results by primary metric, and replaces 8-15 sequential lookups. No contradiction with annotations. The description explains data sources (SEC EDGAR/XBRL for companies, FAERS for drugs) and handling of off-calendar fiscal years.

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 dense single paragraph that front-loads common query patterns. Every sentence adds value without verbosity. It could be slightly more structured with line breaks, but it is efficient and clear for an AI agent.

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

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

Given the tool's complexity with two entity types and multiple data sources, the description covers key aspects: supported types, data origins, entity count limits, output format (paired data + URIs), sorting, and efficiency gains. No output schema exists, so the description explains return values adequately. It could detail the exact structure of the output (e.g., JSON fields), but the current level is sufficient for correct usage.

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

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

Schema coverage is 100%, and the description greatly enhances parameter meaning. For 'type', it lists the two enum values and their implications. For 'values', it explains that for companies it takes tickers/CIKs and pulls 10-K metrics, for drugs it takes names and pulls adverse-event counts, FDA approvals, etc. This goes well beyond the schema's minimal descriptions.

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

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

The description clearly states the tool's function: side-by-side comparison of 2-5 companies or drugs in one parallel call. It lists explicit trigger phrases like 'compare X and Y', 'X vs Y', etc., and differentiates from sequential lookups. The verb 'compare' and resource 'entities' are specific, and it distinguishes between company and drug types.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing strong usage guidance. It also gives context with examples. However, it does not explicitly mention when not to use it (e.g., for single entities) or list alternative tools, though sibling tools like entity_profile are available. Still, the guidance is clear and actionable.

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

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

Description adds significant behavioral context beyond annotations: account requirement, paid plan for certain depth, explicit gaps[] for unanswered facets, 'never invented' policy, and expected latency (15-60s). No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false).

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 well-structured with critical information front-loaded (account requirement and alternative). Each sentence adds unique value. Slightly long but justified given tool complexity; no redundancy.

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

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

Despite no output schema, description thoroughly explains return value: 'findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[]'. Account and usage constraints are fully covered, making the tool's behavior predictable.

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

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

While schema covers 100% of parameters, description enriches semantics: depth parameter explained as 'quick=3, standard=5, thorough=8', question parameter noted as 'broad/multi-part is fine'. Adds value beyond schema definitions.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 932 STRUCTURED data sources... in ONE call'. It distinguishes from siblings like ask_pipeworx by noting it decomposes questions into facets and routes to 3,899 tools in parallel. The verb-resource combination is specific and informative.

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 guidelines are provided: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also notes account requirements and paid plan for 'thorough' depth. No ambiguity about when to use this tool vs alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's safety profile is clear. The description adds value by specifying that results include full schemas with curated examples and are ready to call directly, which is behavioral context beyond annotations.

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

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

The description is well-structured: it starts with the core purpose, then lists domains, then explains capabilities. It is slightly long but every sentence adds value, and it avoids redundancy with the schema.

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 discovery tool with no output schema, the description adequately covers what the tool does, when to use it, what it returns, and how the results are structured. With 33 sibling tools, this description provides sufficient context for an agent to select it appropriately.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing concrete examples ('look up FDA drug approvals', 'analyze housing market trends') and explicitly listing alias parameters (task, q, description, search) in prose, which reinforces the schema and aids 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 uses a specific verb ('Find tools by describing the data or task') and clearly identifies the resource (existing tools) with a long list of example domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools that are more narrow or task-specific.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set', giving clear when-to-use guidance. It also describes the return format and readiness to call, but does not explicitly mention when not to use or provide 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 mark the tool as read-only, idempotent, and non-destructive. The description adds significant behavioral context, including data sources (SEC EDGAR, XBRL, USPTO, etc.), a soft-fail note about the PatentsView API sunset, and the structure of the response (fields like recent_filings, fundamentals, patents, etc.). 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 dense but well-structured, starting with example queries, then the core purpose, then details on behavior, and finally limitations. Every sentence provides useful information; however, it could be slightly more concise without losing meaning.

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

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

The tool has no output schema and only 2 parameters, but the description covers the output implicitly by listing the fields returned, and it addresses limitations (name resolution, patent sunset). For a relatively simple tool with good annotations, this is adequate and complete.

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

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

Both parameters have full schema coverage. The description adds value by specifying that 'type' only supports 'company', and that 'value' must be a ticker or zero-padded CIK (with examples), plus explicitly stating that names are not supported. This goes beyond the schema's 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 provides a 'full cross-source profile of a US public company in ONE parallel call,' with concrete examples like 'Tell me about X' and 'company profile for Microsoft'. This clearly distinguishes it from siblings such as compare_entities and resolve_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?

The description advises agents to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and notes that names are not supported, directing users to use resolve_entity first. This provides clear when-to-use and when-not-to-use guidance along with an alternative.

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

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

Annotations already provide destructiveHint=true and readOnlyHint=false, so the description's 'Delete' aligns. It adds context about clearing 'sensitive data' but does not elaborate on idempotent behavior or error cases. Adequate but minimal added value.

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 with no wasted words. The first sentence states the action, the second provides usage guidance. Front-loaded and efficient.

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

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

Given the tool's simplicity (1 required param, no output schema), the description is largely complete. It covers purpose, usage, and sibling context. Missing details about behavior when key doesn't exist, but that is minor.

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

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

Schema coverage is 100% for the single parameter 'key', with a clear description. The description does not add additional parameter semantics beyond what the schema provides, so baseline score 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 verb 'Delete' and the resource 'memory', specifying the deletion is by 'key'. It explicitly pairs with siblings 'remember' and 'recall', distinguishing its purpose.

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

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

Provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with remember and recall, giving implicit alternatives. Lacks explicit when-not-to-use instructions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds process detail (fetches page, extracts title/description/key links) without contradiction. It provides moderate added value beyond annotations.

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

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

The description is three sentences with the main purpose first, followed by process and use cases. Every sentence is informative and there is no redundancy.

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

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

Given the tool's simplicity (2 params, no output schema), the description covers purpose, process, output format ('single text blob ready to drop at site-root/llms.txt'), and use cases, making 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?

Schema coverage is 100% with both parameters described. The description does not add significant meaning beyond the schema; it hints at output contents but doesn't elaborate on parameters. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate', the resource 'llms.txt file', and the scope 'for any URL'. It differentiates from sibling tools, none of which produce llms.txt.

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

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

The description lists explicit use cases: indexing a client's site, drafting for own project, or auditing a competitor. It does not specify when not to use or name alternatives, but the context is clear and sufficient given the tool's uniqueness.

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

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

Annotations already declare readOnlyHint and idempotentHint; description adds that it lists active subscriptions and the optional include_inactive parameter, but no further behavioral details.

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

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

Two concise sentences, front-loading purpose and return fields, 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?

Adequately covers purpose, return fields, default behavior, and usage guidance; no output schema needed as fields are described.

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%; description parallels schema but adds no new meaning beyond the default behavior of listing active subscriptions.

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

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

Clearly states action 'List' and resource 'subscriptions', specifies return fields, and distinguishes 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?

Explicitly advises to use for reviewing before adding more or finding an ID to cancel, providing clear 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?

Annotations provide no hints (readOnlyHint false, etc.), but description fully compensates by disclosing rate-limiting, that it's free, no quota impact, and that team reads digests daily. 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?

Six sentences, no redundancy, front-loaded with purpose, then usage, then constraints. Every sentence earns its place; 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 no output schema, description covers all essential aspects: purpose, categories, usage guidance, constraints (rate limit, quota), and behavior. Nothing missing for a feedback tool.

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

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

Schema coverage is 100%, yet description adds significant meaning: clarifies enum values with examples, advises specificity for message, recommends 1-2 sentences, and sets character limit. Goes beyond what schema provides.

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

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

The description clearly states a specific verb ('Tell') and resource ('Pipeworx team'), enumerates exact use cases (bug, feature, data_gap, praise, other), and is distinct from sibling tools which are all research or subscription tools.

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

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

Explicitly instructs when to use each feedback type, warns not to paste end-user prompts, specifies rate limits (5 per identifier per day), and mentions it's free with no quota impact. Provides clear context for alternative actions.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: data source (CF analytics-engine), anonymity (no PII), and caching (5min-1h), which go 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 concise (5 sentences) and well-structured: primary purpose first, then use cases, then technical details. No unnecessary words.

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

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

Despite no output schema, the description fully explains what is returned (top tools, top packs, total call volume) and the aggregation logic. It leaves no ambiguity for an AI agent to use the tool correctly.

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

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

Only one parameter ('window') with an enum, and the description adds semantic guidance: 'shorter windows surface what's hot right now; longer windows show steady-state demand.' Schema coverage is 100%, so no gap, but the description enhances 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 returns trending data on which tools and packs other AI agents are calling, with options for different time windows. It distinguishes from siblings like 'ask_pipeworx' and 'discover_tools' by focusing on aggregate usage signals.

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?

Three explicit use cases are provided, giving clear context for when to use the tool. It does not explicitly mention when not to use it, but the use cases are sufficiently distinct to guide selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint false. The description adds extensive behavioral context: walks child markets, checks ordering, computes partition_check, uses semantic anchor with Jaccard similarity, filters partitions, and performs fill check against live CLOB depth. 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 thorough but slightly verbose, with multiple sections (REQUIRES, main description, SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). However, it is front-loaded with the essential requirement and each part adds value. A more streamlined structure could improve conciseness.

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

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

Given the tool's complexity (two modes, multiple checks, no output schema), the description is complete. It explains prerequisites, behavior, return structure (opportunities[], partition_check, fill check details), and covers edge cases like low similarity and placeholder filtering.

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%, but the description adds significant meaning: explains the difference between event and topic modes, gives example inputs, and describes how each mode works (e.g., partition_check in event mode, semantic anchor in topic mode). This enriches the schema's minimal descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between event mode (single-event) and topic mode (cross-event), providing specific examples. This differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly requires one of `event` or `topic`, and warns that calling with no arguments fails. It recommends event mode for specific markets and topic mode for cross-event scanning. It also mentions polymarket_fill_risk for custom sizing, providing clear when-to-use and alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavior details beyond annotations: cache (1h KV), model internals (GDP, GDELT, partition_overround), edge computation, and diagnostics for empty segments. 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 very long and dense, with multiple sections and inline details. While structured into segments, it could be more concise by trimming repetitive explanations or moving some internals to a separate doc. It front-loads purpose well but is not optimally concise.

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

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

Given the complexity (9 parameters, multiple models, filtering knobs, response structure, and caching), the description is exceptionally complete. It covers what each segment does, how edges are calculated, tradeable-edge filters, diagnostics, and caching behavior, making it fully actionable for an agent without an output schema.

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

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

Schema coverage is 100%, baseline 3. The description provides additional context beyond the schema, e.g., slippage_pp explains Polymarket fees and adjustment suggestions, min_liquidity clarifies 'dropping thin-book opportunities'. This adds significant value.

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

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

The description clearly states the tool scans top Polymarket markets to return opportunities where Pipeworx data disagrees with market price. It explicitly states the intended use: 'what should I bet on today' and distinguishes itself from sibling tools by detailing its unique segments and models.

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 usage context: agents discover opportunities without paging hundreds of markets. It explains when to adjust knobs like min_liquidity and max_spread_pp and implies alternatives like polymarket_arbitrage. However, it lacks explicit when-not-to-use guidance or comparison to all siblings.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds significant behavioral details: snapshot gaps, decay computation from daily closes, TTL bounds, and response structure. No contradictions with annotations.

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

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

The description is detailed but every sentence adds value. It front-loads the main concept and then methodically explains args, response fields, and limits. No redundant or vague statements.

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

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

Given the tool has no output schema, the description fully explains the return values (tracked, expired, snapshot_dates) with detailed field semantics. It also accounts for limits and edge cases (gaps, TTL). The description is complete for an agent to understand and correctly 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 coverage is 100% for the two parameters, so baseline is 3. The description adds clamping behavior (days clamped 2-30) and default values, which are not in the schema. It also explains parameter effects on response. This extra context justifies a score of 4.

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

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

The description clearly states the tool's purpose: it provides edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and whether it is decaying. It distinguishes itself from siblings by focusing on historical analysis rather than current edges, as seen in the contrast with 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 implies when to use the tool (to evaluate edge freshness and decay) and provides context (fresh vs. stale edges). It mentions limits and gaps. However, it does not explicitly compare with sibling tools or state when not to use it, which would strengthen 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint as false. The description adds rich behavioral details: walks the order-book ladder, returns verdict (clean/degraded/cannot_fill), identifies thin legs and forced directional risk, and explains output fields comprehensively.

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 thorough but well-structured: first sentence states purpose, then REQUIRES, then two modes with output fields, then usage advice. It is slightly verbose but every sentence adds value; front-loads critical information.

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

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

Given the tool's complexity (two modes, no output schema, risk warnings), the description is complete. It covers all necessary context: when to use, parameters, output fields, risk of partial fills, and forced directional risk, enabling correct agent invocation.

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

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

Schema coverage is 100%, yet the description adds significant meaning beyond schema descriptions: explains size_usd differently for single-market vs basket, clarifies side auto-default for basket, and details slug/URL formats. This goes well beyond the baseline of 3.

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

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

The description clearly states the tool does a 'realizable-vs-theoretical edge check against live CLOB order-book depth', specifies single-market and basket modes, and explicitly differentiates from siblings like polymarket_arbitrage and polymarket_edges by advising usage before acting on their signals.

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 when to use (before arbitrage signals or trades above ~$500), explains required parameters (market or event), and warns against partial basket fills converting arb into directional positions, providing clear when-to-use and when-not-to-use guidance.

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

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

The description adds significant behavioral context beyond annotations. It details the two operational modes, the response structure (leg prices, matched spreads, top_spreads_pp), and the safety fields (compatibility_warning conditions, temporal_alignment, skip counters). This fully discloses how the tool determines whether a spread is valid.

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

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

The description is relatively long but well-organized with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Key information is front-loaded. Some redundancy exists (e.g., repeating the shortcut list), but overall it is efficient for the complexity.

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

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

Given the tool's complexity (two venues, multiple modes, safety checks) and the absence of an output schema, the description thoroughly explains the response structure, edge cases (compatibility warnings, temporal misalignment), and counters (skipped_cross_type/subtype). It provides sufficient context for an AI agent to correctly 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?

All three parameters are documented in the schema (100% coverage), so baseline is 3. The description adds value by explaining the interaction between modes (topic vs explicit, overrides) and providing examples. It does not deeply explain the format of kalshi_event_ticker or polymarket_event_slug beyond the schema, but the use cases are clear.

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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It differentiates two modes (topic shortcuts vs explicit pairings) and explains the spread direction (Kalshi minus Polymarket). This distinguishes it from sibling tools like polymarket_arbitrage.

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

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

The description explains when to use the tool: to find arbitrage opportunities when the same outcome is priced differently across venues. It warns that most pre-mapped topics return compatibility warnings and that spreads require temporal alignment. Explicit guidance on when not to use it relative to alternatives is missing, but the warning about meaningless spreads is helpful.

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

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

Annotations already cover read-only and idempotent; description adds scoping detail (anonymous IP, key hash, account ID) and retrieval behavior, which is valuable beyond structured data.

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

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

Four sentences front-loaded with main action. No fluff, though could be slightly more concise. Good structure.

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

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

No output schema, but description explains return behavior (value or list of keys). Pairs with remember/forget. Complete for a simple retrieval tool.

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

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

Schema coverage is 100% with clear description of key parameter. Description adds no new meaning beyond schema; baseline of 3 appropriate.

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

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

The description clearly states the tool retrieves a value or lists keys, distinguishes from siblings 'remember' and 'forget', and specifies scoping to user identifier.

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

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

Explicitly says to use for looking up stored context without re-deriving, and pairs with remember/forget. Lacks explicit when-not-to-use but provides solid guidance.

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

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

The description states that setting mark_read:true will flag returned events as read, modifying state. This directly contradicts the readOnlyHint: true annotation which indicates no state changes. The contradiction severely undermines transparency.

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

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

The description is four sentences, front-loaded with the primary action and results. It is efficient with no wasted words, though a more structured breakdown of parameter behaviors could improve clarity.

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

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

Given the absence of an output schema, the description partially compensates by mentioning source, citation_uri, and raw event payload. It covers filtering, mark_read, and polling, but omits details on limit and unread_only, and the output shape is incomplete.

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. The description adds context for type and since parameters and mentions mark_read, but does not cover limit or unread_only. It adds marginal 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 pulls fired events from the subscription feed, specifying the resource and what each alert carries. It provides a clear sense of purpose but does not explicitly differentiate from sibling tools like list_subscriptions.

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

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

The description mentions that polling works fine and provides an alternative API endpoint, implying when to use this tool. However, it does not explicitly state when not to use it or compare with alternatives, leaving the guidance 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 mark readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds critical context: fan-out to multiple sources (SEC, GDELT, GNews, USPTO), rate-limiting handling (GDELT→GNews fallback), and soft-fail for USPTO. This goes well beyond annotation defaults.

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 densely packed, front-loaded with example queries, and every sentence adds value. It could be slightly more structured (e.g., bullet points for sources) but remains very efficient for its 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?

Without an output schema, the description fully defines the return shape: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' It also covers edge cases (fallsback, soft-fail, API sunset) and provides enough context for confident 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 covers 100% of parameters with descriptions. The description enriches this by explaining `since` accepts both ISO dates and relative shorthand ('7d', '30d', '3m', '1y'), and `value` accepts ticker or padded CIK. Provides typical value advice ('Use "30d" or "1m" for typical monitoring').

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 'change feed for a company in the last N days/weeks/months in ONE parallel call' and lists specific content types (SEC filings, news, patents) with example queries. It explicitly distinguishes itself from entity_profile for static data.

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

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

Provides concrete when-to-use examples ('What's new with X', 'latest on Y') and explicitly directs to entity_profile for static needs. Details fallback behavior (GDELT→GNews) and version constraints (USPTO PatentsView API sunset), giving clear guidance on tool selection.

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 idempotentHint=true and destructiveHint=false. The description adds behavioral context beyond annotations: key-value pair scoped by identifier, persistence window (24h anonymous, persistent authenticated), and the consequence of not needing to look up again. It could mention overwriting behavior, but annotations cover idempotency.

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

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

The description is a single paragraph, front-loaded with purpose, then usage, then technical details. Every sentence contributes without redundancy. Length is appropriate for the tool's simplicity.

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 (2 params, simple key-value), the description covers all necessary context: purpose, when to use, behavior, persistence, and sibling tools. No output schema needed.

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

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

Schema-description coverage is 100% (both key and value have descriptions). The description adds illustrative examples for key (e.g., 'subject_property') and value ('any text'), but the schema already provides adequate meaning. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It provides specific examples of what to save (resolved ticker, target address, etc.) and explicitly distinguishes it from sibling tools recall and forget.

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

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

The description explicitly says when to use the tool: 'when you discover something worth carrying forward' and mentions the context for not using alternatives: 'Pair with recall to retrieve later, forget to delete.' It also clarifies persistence differences for authenticated vs anonymous users.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that each call cascades through several endpoints internally, which is useful behavioral context. 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 comprehensive but somewhat lengthy. However, it is well-structured with examples, supported types, and returns. Every sentence adds value, and key usage guidance is front-loaded.

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

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

Despite lacking an output schema, the description fully explains return values for both entity types, including citation URIs and behavior variations. It covers all necessary context for invoking the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The tool description greatly enhances meaning by detailing what each entity type returns (e.g., for company: ticker + CIK + company_name + citation URI), and what inputs are accepted (ticker, CIK, name). This goes well beyond the schema.

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

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

The description explicitly states the tool resolves names to canonical IDs, provides clear examples ('What's the ticker for…'), and lists supported entity types (company, drug). It clearly distinguishes from sibling tools like compare_entities or entity_profile by focusing on identifier lookup.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' giving clear precedence. It also states it replaces 2-3 manual lookups, helping the agent understand when to invoke this tool over alternatives.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already declare non-destructive, idempotent behavior. The description adds that it internally calls ai_visibility_check and returns a ranked list with score, confidence, and signal density. This provides context beyond annotations but does not contradict them. A slight gap is no mention of failure modes or rate limits, but given annotations cover safety, 4 is justified.

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 concise: 4 sentences, each serving a clear purpose (purpose, mechanism, example, return). No redundancy or filler. Front-loaded with the key action and resource, making it 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?

Given 4 parameters, 100% schema coverage, no output schema, the description sufficiently explains both input (via schema + semantic additions) and output ('Returns ranked list with score, confidence, signal density per entity'). The internal call to ai_visibility_check is disclosed, providing full transparency. No gaps for effective use.

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

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

Schema coverage is 100% with descriptions for all params. The description adds critical meaning: 'First entry treated as the subject for narrative; rest are competitors' (not in schema), and usage tips like 'Omit for just workers-ai' for models. This significantly aids correct parameter usage beyond what the schema alone provides.

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

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

The description clearly states the tool compares AI visibility across multiple entities, using a specific verb ('compare/scan') and resource ('AI presence'). It distinguishes itself from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by detailing its mechanism (probes each entity, ranks by score) and use case ('competitive AI-marketing audits').

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 explicitly says when to use: 'Useful for competitive AI-marketing audits' and provides a concrete example: 'does Claude know about us as well as our competitors?'. It implicitly excludes single-entity checks by referencing ai_visibility_check as the internal probe, distinguishing from that sibling. No when-not-to-use is needed given the specificity.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds significant detail: the tool fans out to multiple services, returns a structured summary, handles partial failures gracefully, and notes that first bundlephobia measurement can take 5-30 seconds. 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 a single paragraph but well-structured, starting with the main purpose and then detailing behavior, output, and limitations. It is relatively long but every sentence provides valuable information. A slightly more structured format (e.g., bullet points) could improve scannability, but it is still clear.

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

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

Given there is no output schema, the description thoroughly explains the return value structure (summary block fields, per-advisory details, links, alternative versions). It also covers edge cases like partial failures, timeouts, and ecosystem restrictions. This completeness compensates for the lack of output schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minor context by mentioning scoped packages are accepted for the 'package' parameter and reinforcing that 'version' defaults to latest. While useful, it does not significantly expand upon the schema's parameter descriptions.

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

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

The description clearly states the tool's purpose: a composite check for deciding whether to add an npm package, covering safety, popularity, size, and cost. It distinguishes itself from siblings by specifically targeting npm packages and combining deps.dev and bundlephobia data, which no other sibling tool does.

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 the tool: when an agent asks about package safety, popularity, or size. It also specifies that it's NPM ecosystem only and directs users to deps.dev:version for other ecosystems. This provides clear usage context and alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds context about the returned data fields, which is useful beyond annotations. It does not mention any limitations or edge cases, but the safety profile is clear from annotations.

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

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

Two sentences with no fluff. Front-loaded with verb and resource, immediately conveying the tool's purpose. Every word is necessary.

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 rich annotations and existing output schema, the description is complete. It specifies the data source (DBLP), return fields, and required parameter, without needing to repeat schema details.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description does not add new meaning to parameters beyond what the schema provides, earning a baseline score of 3.

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

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

Description clearly states this tool searches DBLP authors by name, specifying the resource (authors) and what it returns (canonical id, affiliation, ORCID). This effectively distinguishes it from sibling tools like search_publications or search_venues.

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?

No explicit guidance on when to use this tool versus alternatives like search_publications. The description implies it is for author tasks, but lacks explicit context or exclusion statements.

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, etc. Description adds default page size and max results, which is useful operational 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?

Two sentences, no filler. Front-loaded with purpose and key constraints. Every word adds value.

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

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

With complete schema descriptions, rich annotations, and an output schema, the description is sufficient for correct invocation. Covers match criteria and 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?

Schema coverage 100%, so baseline 3. Description adds cognitive load reduction by summarizing match fields and pagination defaults (default 30, max 1000), enhancing usability.

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

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

Clearly states it searches DBLP publications with specific match fields (title, author, year, venue). Distinguishes from sibling tools like search_authors and search_venues.

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?

Implies usage for publication search with specified fields. Lacks explicit when-not or alternatives, but context with siblings makes it clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which cover safety and idempotency. The description adds that it searches both conferences and journals, providing scope detail, but otherwise adds no behavioral context beyond annotations.

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

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

The description is a single, focused sentence that front-loads the purpose. Every word is necessary and there is no extraneous 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?

The tool is simple (3 parameters, all documented in schema, annotations present, output schema exists). The description covers the scope (conferences + journals). It is mostly complete but could mention that the search is free-text or partial matching, which is implied by examples but not explicit.

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

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

Schema description coverage is 100%, so the schema already documents all parameters (query, hits, first). The description does not add any additional meaning or usage details for these parameters beyond what is in the schema.

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

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

The description clearly states the tool searches DBLP venues, explicitly mentioning both conferences and journals. This specific verb-resource combination distinguishes it from sibling tools like search_authors and search_publications.

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?

No guidance is provided on when to use this tool versus alternatives. The sibling list includes many other tools, but there is no mention of when search_venues is appropriate or when another tool would be better.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. Description goes beyond by disclosing embedding model (BGE-base-en), similarity metric (cosine), chunking (500-char overlapping windows), size limit (200K chars with truncation and flagging), and output details (offsets, similarity scores). This fully characterizes 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?

Description is well-structured: front-loaded with purpose and use case, then technical details. Every sentence adds value. Slightly verbose but still efficient. 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?

Despite no output schema, description clearly explains what is returned (top-N passages with character offsets and similarity scores). It also covers truncation behavior and pairing advice. Complete for a search tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning by explaining 'text' as already-fetched content, 'query' as natural language with examples, and 'limit' default and range. This enhances understanding beyond the schema 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?

Description clearly states it performs semantic search inside a fetched record, with examples like SEC 10-K or article. It distinguishes itself from siblings by emphasizing 'inside a fetched record' and pairing with ask_pipeworx_grounded, which is a sibling tool. The verb 'search' and resource 'record text' are specific.

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 explicitly says to use when the record is too big to cram into the prompt, saving context. It also mentions pairing with ask_pipeworx_grounded. However, it does not explicitly state when not to use or list alternatives among siblings beyond the one partner 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 provide readOnlyHint=false and idempotentHint=true, but the description adds substantial context: auth requirements, type-specific parameter formats with examples, delivery channel behaviors (e.g., webhook auto-disable after 10 failures, SMS 10/day cap). 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 with purpose first, then prerequisites, supported types with examples, and delivery details. Every sentence adds value, though it is slightly longer than necessary. Could be more terse, but current organization is clear.

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

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

Given the tool's complexity (nested objects, no output schema), the description covers auth, type param formats, delivery options, and limits. Lacks explicit mention of idempotency behavior (annotations state idempotentHint=true, but description implies each call creates new subscription). This minor gap prevents a perfect score.

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

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

Schema coverage is 100%, but the description adds significant value beyond the schema by providing concrete examples for each type (e.g., sec_8k: {ticker, items}) and explaining delivery constraints (email validation, phone verification, webhook signing). This lifts the score above the baseline of 3.

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

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

The description clearly states 'Create a proactive monitoring subscription' with a specific verb and resource. It distinguishes from sibling tools like list_subscriptions (list) and unsubscribe (remove). Returns the subscription ID, making the action 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 prerequisites (Pipeworx OAuth account, phone verification for SMS) and lists supported types and delivery channels. It implicitly tells when to use (to create subscriptions) but does not explicitly contrast with alternatives like list_subscriptions or recent_alerts.

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?

Describes return content: category-bucketed examples with exact tool shapes from a live catalog. Adds context beyond annotations (readOnly, idempotent) about dynamic results. 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?

Single paragraph front-loads purpose and alternative phrasings. Every sentence adds value. No wasted words.

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

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

Given the tool's simplicity (1 optional param, no output schema), the description fully covers purpose, usage, parameter behavior, and return content context.

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

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

Schema description coverage is 100% and baseline is 3. Description adds value by explaining behavior with and without the topic parameter, enhancing clarity beyond schema.

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

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

Clearly states it is the onboarding entry point that returns example questions. Lists categories and distinguishes from sibling tools by saying 'use this FIRST' when the agent doesn't know what Pipeworx can do.

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

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

Explicitly says when to use: when you don't know what Pipeworx can do or to learn meta-tools. Explains optional topic parameter. Implies when not to use by suggesting it's for initial discovery, but lacks explicit alternatives.

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

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

Beyond annotations (non-destructive, idempotent), the description clarifies that the row is deactivated not deleted and that historical events remain available, adding significant behavioral context.

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

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

Two concise sentences that front-load the action and efficiently convey purpose, ownership, and behavioral impact with no redundant information.

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

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

Given the single parameter, no output schema, and sibling tools, the description fully covers purpose, ownership, and deactivation behavior, providing complete context for the agent.

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

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

The input schema covers the single parameter 'id' with description. The description does not add further semantic details beyond the schema, 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 cancels a subscription by id and distinguishes it from subscribe and list_subscriptions by explaining the deactivation behavior.

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

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

The description explicitly states ownership enforcement ('only cancel your own subscriptions'), providing a clear usage constraint. It implies when to use this tool (to cancel a subscription) versus alternatives like subscribe.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful behavioral details: returns a verdict, extracted structured form, actual value with pipeworx:// citation, and percent delta, and mentions it replaces 4-6 sequential calls, enhancing transparency beyond annotations.

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

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

The description is well-structured, starting with examples, then usage, domain, and return values. It is somewhat lengthy but every sentence contributes value. Could be slightly more concise, but not overly verbose.

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

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

Despite having no output schema, the description fully explains what the tool returns and its scope. Given the complexity of replacing multiple sequential calls, the description is comprehensive and leaves no major gaps.

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

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

With only one parameter and 100% schema description coverage, the schema already explains the parameter well. The description adds natural-language examples and domain constraints but does not significantly expand on the schema's existing description, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, specifically company-financial claims. It provides examples of use cases like 'fact check' and lists the returned verdict types, distinguishing it from siblings by noting it replaces multiple sequential calls.

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

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

The description explicitly states when to use ('whenever the agent needs to check whether something a user said is factually correct') and specifies the domain (company-financial claims via SEC EDGAR + XBRL), implying limitations. However, it does not explicitly list when not to use or mention alternatives.

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