Always Seven

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

The description adds significant behavioral context beyond annotations: default model is free, Anthropic requires BYO key and direct payment, returns per-model details and combined view. No contradictions with annotations (all hints are consistent).

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

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

Description is concise (4 sentences) with front-loaded purpose, then key details. No redundant or missing information. Each sentence adds value.

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

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

No output schema, but description adequately explains return structure: per-model score, confidence, signals, raw_response, plus combined view. All 4 parameters are described. Covers all necessary aspects for selection and invocation.

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

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

Schema description coverage is 100%, baseline 3. Description adds meaning: explains default model, purpose of _apiKey, and context parameter helps disambiguate. Provides example values. Slightly above baseline.

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

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

Description clearly states the tool probes LLMs for entity knowledge and scores visibility. It uses specific verbs ('probe', 'score') and resources ('LLMs', 'visibility') and differentiates from siblings by mentioning AI-marketing audits, a unique use case not covered by tools like scan_competitor_ai_presence.

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

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

Description explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains when to use the _apiKey parameter (to also probe Anthropic). However, it does not directly compare to similar sibling tools or state when not to use this tool, so not a 5.

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

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

The description goes beyond annotations, revealing the always-7 behavior and that parameters have no effect, which is crucial for correct invocation.

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 clear sentences, front-loaded with main purpose, no wasted words.

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

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

For a simple, humorous tool with full annotations and output schema, the description adequately covers all behavioral nuances.

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

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

Schema already describes parameters; the description adds that they are accepted but have no effect, providing critical behavioral context beyond schema.

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

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

The description clearly states the tool calls an API that 'always returns 7', specifying the verb-resource relationship and the deceptive nature. It distinguishes from siblings by highlighting unique 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 implies the tool is for obtaining the number 7 despite claiming randomness, but lacks explicit guidance on when to use vs alternatives or when not to use.

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

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

While annotations already declare read-only, idempotent, and open-world hints, the description adds meaningful behavioral context: it routes to 5,529 tools, fills arguments automatically, and returns stable pipeworx:// citation URIs. It doesn't contradict annotations, and the extra details help the agent predict the tool's operation.

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 highly structured: it opens with a strong directive, lists use-case examples, and ends with escalation paths. Every sentence contributes value, though it could be tightened without losing meaning. The front-loading of 'PREFER OVER WEB SEARCH' is effective.

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

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

For a complex routing tool with no output schema, the description explains what it does, when to use it, how it behaves (routing, citations), and provides concrete examples. It covers the agent's needs well, though it doesn't mention potential latency or the exact format of the structured answer beyond citations.

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

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

Schema coverage is 100% with all six parameters documented as aliases for 'question'. The description adds no new parameter-level semantics, but this is acceptable because the schema already fully explains the single meaningful parameter. The extensive examples in the description compensate slightly, but the schema carries the burden.

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 answers factual questions with citations, listing specific domains (SEC, FDA, FRED, USPTO, etc.) and explicit user-phrase triggers. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point.

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

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

Provides explicit when-to-use guidance: prefer over web search for factual queries, use for 'what is', 'look up', 'find', etc. It also gives clear alternatives: use ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions. This is exemplary.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description goes well beyond that by disclosing that candidate routing improvements are enabled live whenever under test, that the last candidate was retired on outcome evidence, and that the tool is a full working router rather than a fallback. This is rich behavioral context beyond the annotations.

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

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

The description is four tightly packed sentences, with the most important identity and scope information front-loaded. Each sentence adds a distinct piece of value: what it is, current state, usage guidance, and clarifying caveat. There is no filler or redundancy.

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

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

For a flexible router with no output schema, this description is complete: it explains the tool's function, current operational status, relationship to ask_pipeworx, and experimental behavior. The lack of output schema detail is mitigated by the explicit statement that the response shape is identical to ask_pipeworx. It gives the agent everything needed to invoke and understand the tool correctly.

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

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

The input schema has 100% coverage, documenting all six parameters, including the primary 'question' field and its aliases. The description only mentions 'same arguments' without adding parameter-level meaning. Since the schema fully carries the semantic load, the 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 this is a beta universal router that 'Ask's natural-language questions and routes to the same 5,529 tools as ask_pipeworx with the same response shape. It explicitly positions itself as the experimental edge of ask_pipeworx, distinguishing it from the stable sibling by live candidate routing improvements.

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 tells the user when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also adds current state context (no active candidate, so it matches ask_pipeworx exactly) and explains that results are compared against the stable router to decide merges. This provides a clear decision boundary without ambiguity.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses the return structure {answer, evidence, confidence, source, fetched_at, refusal_reason} and refusal reasons (not_in_source, no_tool_match, etc.). It also explains the extraction constraint 'using ONLY what the tool result contains'.

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

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

The description is dense but every sentence earns its place: purpose, mechanism, return format, refusal semantics, and usage trade-off. It is well-structured and front-loaded with the key differentiator: hallucination-resistant.

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

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

Given the tool's complexity (routing across 5,529 tools), the description thoroughly covers purpose, behavior, return values, refusal reasons, and cost considerations. No output schema exists, so the description appropriately specifies the exact success and failure return shapes.

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 all parameters are documented as aliases for the natural language question. The description does not add extra parameter semantics beyond what the schema already provides, earning the 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?

The description clearly states this is a hallucination-resistant answer mode for high-stakes reads, with a specific verb ('EXTRACTS the answer') and resource (Pipeworx tool routing). It distinguishes itself from sibling ask_pipeworx by emphasizing grounded extraction and refusal behavior.

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

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

Explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on...'. It also gives a clear alternative: 'prefer ask_pipeworx for casual lookups' and notes the cost trade-off of one extra LLM call.

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

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

The description goes far beyond the annotations, detailing fan-out examples, response shapes, resolver contract with confidence levels, parent event extraction, news field fallbacks, safety mechanisms for low-confidence matches, closed market handling, wide spread warnings, and cancellation rule parsing. This provides rich behavioral context that annotations alone cannot capture.

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 detailed and includes extensive examples and edge cases, which is valuable for a complex tool, but it is lengthy and could be better structured with more separation of concerns. The front-loading of purpose is good, but the density of information may overwhelm 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, the absence of an output schema, and the rich annotations, the description covers nearly every aspect: resolution, fan-out, response fields, safety, edge cases (closed markets, wide spreads), and even resolution-rule risk. It leaves little ambiguity for the AI agent.

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

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

Schema coverage is 100%, but the description adds significant value by explaining how the 'market' parameter accepts slugs, URLs, or question text, and by clarifying the 'depth' parameter's effect (quick vs thorough) and the 'include_raw' parameter's recommendation (false to keep responses under 20KB, true for full payloads).

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

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

The description opens with a clear verb+resource statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It immediately conveys the tool's primary function and distinguishes it from sibling tools by focusing on comprehensive research rather than specific analytics like arbitrage or edge tracking.

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 use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides concrete examples of when to invoke the tool but does not explicitly mention when not to use it or contrast with alternatives like polymarket_edges or polymarket_arbitrage.

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=false. The description adds significant behavioral context: parallel call, results sorted by primary metric, returns paired data and pipeworx:// citation URIs, handles off-calendar fiscal years. 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 informative but slightly verbose. It front-loads trigger phrases and key instructions. Every sentence adds value, but could be tightened without losing clarity.

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

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

For a tool with no output schema, the description adequately explains return data: specific financial metrics for companies, adverse-event and trial counts for drugs, sorting by primary metric, citation URIs. It also mentions edge case handling (off-calendar fiscal years). Complete enough.

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 expands on both parameters: type enum values with detailed explanations (company vs. drug data sources), values array with constraints (2-5 items), examples for both types (tickers/CIKs for companies, names for drugs). Adds meaning beyond schema.

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

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

The description uses specific verbs and resources: 'compare', 'side-by-side comparison', 'pulls LATEST 10-K revenue + net income + cash + long-term debt' for companies, and 'FAERS adverse-event counts, FDA approval counts, active trial counts' for drugs. It distinguishes from siblings by asserting it replaces 8-15 sequential lookups and should be preferred for comparisons.

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

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

Explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It lists example queries that trigger this tool and specifies entity types and count requirements (2-5). No when-not-to-use stated, but the guidance is clear.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses account requirements, paid plan needs, latency expectations (15-60s, up to ~90s for thorough), the exact return packet structure (findings with evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop), and how large records are semantically excerpted. It also states that gaps[] are explicit and findings are never invented, providing deep behavioral context.

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

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

The description is long but densely packed with non-redundant facts: source count, parallel routing, return format, gap behavior, citation resolvability, iteration, contradictions, semantic excerpting, latency, and alternatives. It is front-loaded with the account caveat and a pointer to a fallback tool. Every sentence earns its place, and the structure is logically ordered from prerequisites to purpose to usage to behavior.

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

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

There is no output schema, so the description serves as the primary documentation of the return value. It fully describes the findings packet, gaps[], contradictions[], citation_uri behavior, hop field, and use-case fit. It even warns about when the tool returns mostly empty gaps and gives example questions. Given the tool's complexity, this is exceptionally complete.

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

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

The input schema already has 100% description coverage, including a detailed enum description for 'depth' (facets, hops, contradiction scan). The tool description reiterates the paid note for 'thorough' but adds no new technical semantics beyond the schema. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and 'Decomposes your question into focused facets, routes each to the right one of 5,529 tools IN PARALLEL'. It also explicitly distinguishes itself from open-web search and sibling tools like ask_pipeworx, making its unique purpose unmistakable.

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

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

The description provides explicit usage guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It also explains depth value choices and their trade-offs, exceeding typical tool descriptions.

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. Description adds that results include full input schemas and are ready to call directly, which is behavioral context beyond annotations. 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?

Front-loaded with purpose, then usage, then return details, then when-to-call. Some redundancy in listing domains could be trimmed, but overall every sentence adds value. Length is justified by the specificity of use case.

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

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

Given no output schema, the description fully explains return value (names, descriptions, schemas with examples, ready to call). With 6 parameters fully documented in schema, no gaps remain. The description covers all aspects needed for the agent to use the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. Description mentions aliases for query but adds no new semantic meaning beyond what the schema's parameter descriptions already provide. The listing of domains in the description is not parameter-specific.

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

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

Clearly states the tool finds tools by describing data or task, lists specific domains, and distinguishes itself as a meta-discovery tool to call first. Verb 'find tools' plus resource 'by describing data/task' is specific and unique among siblings.

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

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

Provides explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set.' It implies when to use but does not explicitly state when not to use or list alternatives, though the sibling context makes natural 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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by detailing the fan-out across multiple sources, listing specific return fields, and noting the patents API sunset. No contradictions with annotations.

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

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

The description is a single paragraph but well-organized with example queries at the start, a clear statement of purpose, and a structured list of returned data. It is informative without being overly verbose, though it could be slightly more concise.

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

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

Without an output schema, the description fully explains what the tool returns: specific fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) with source details and edge cases (patents sunset, names not supported). This covers all critical context for agent decision.

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 meaning beyond the schema: it explains that 'value' accepts ticker or zero-padded CIK (not names), and type is restricted to 'company' with future types mentioned. This context helps agents format parameters correctly.

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 starts with clear user query examples, states it provides 'full cross-source profile of a US public company in ONE parallel call', and enumerates returned data sources. This distinguishes it from sibling tools like resolve_entity and avoids ambiguity.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups for holistic view', provides alternative when only a name is known ('use resolve_entity first'), and notes that patents may soft-fail. This gives 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?

Discloses destructive nature (delete) aligning with destructiveHint=true, but lacks details on side effects or permissions.

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

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

Two concise sentences, front-loaded with key action and usage context, 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?

Simple tool with single parameter and no output schema; description fully covers purpose and usage guidance.

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% with description for 'key', but tool description adds no extra meaning beyond schema.

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

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

Description uses specific verb 'Delete' and resource 'memory by key', clearly distinguishing from sibling tools 'remember' and 'recall'.

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

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

Explicitly states when to use (stale context, task done, clear sensitive data) and pairs with 'remember' and 'recall'.

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

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

Adds significant behavioral context beyond annotations: fetches page, extracts title/description/key links, emits standard markdown format. 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?

Efficient, front-loaded sentences with no waste. Purpose, process, and use cases are clearly separated.

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

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

Despite no output schema, the description explains the output format (text blob, standard markdown) and covers all necessary context for a simple generation tool.

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

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

Schema covers 100% of parameters with descriptions, so the description doesn't need to add much. The baseline 3 is appropriate; no extra parameter detail needed.

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

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

The description clearly states the tool generates an llms.txt file for a URL, specifies the output format, and lists use cases. It distinguishes itself from siblings by being the only tool for this specific task.

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 (indexing clients, drafting own project, auditing competitors) but does not explicitly state when not to use it or mention alternatives.

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

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

The description adds value beyond annotations by listing return fields. However, it does not disclose any potential pagination limits, ordering, or the time range of subscriptions. Annotations already cover read-only and idempotent behavior, so the bar is lowered.

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

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

The description is two sentences, front-loading the core action and return fields. No extraneous information. 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?

For a simple list tool with one optional parameter and no output schema, the description sufficiently lists the return fields, covers the parameter via schema, and provides usage context. No gaps.

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

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

The input schema has 100% description coverage with the 'include_inactive' parameter clearly documented. The description does not add extra semantics for the parameter, which is acceptable given the schema's completeness.

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 verb 'List', the resource 'subscriptions', and the scope 'caller's active'. The sibling tools 'subscribe' and 'unsubscribe' provide clear differentiation.

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

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

The description provides explicit guidance on when to use the tool: 'review what you're monitoring before adding more or to find an id to cancel'. This is clear and actionable, though it does not mention when not to use it.

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

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

The description discloses important behavioral traits beyond annotations: rate limiting to 5 per identifier per day, that it's free and doesn't count against quota, that filing without an account returns a claim_token, and that pass-back later reads status/resolution. These details are not present in annotations and add real transparency. 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 longer than average but every sentence earns its place: purpose, use cases, exclusion, message guidance, claim_token workflow, digest cadence, rate limit, and quota. It is front-loaded with the core purpose and structured logically, making it easy for an agent to parse quickly.

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

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

Given the tool's moderate complexity, the description covers the full workflow: when to use it, what to include, how the claim_token works, and operational constraints. It also hints at the return value (a claim_token) without needing an output schema. The description is complete enough for an agent to invoke and handle the response 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%, giving baseline 3. The description adds meaning by clarifying claim_token usage, advising users to describe issues in terms of Pipeworx tools/packs, and warning against pasting end-user prompts. This goes beyond the schema's field descriptions, though it doesn't deeply explain the context object's pack/tool/vertical usage beyond names.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from sibling tools by defining its scope (bug, feature, data_gap, praise) and by explicitly excluding tools from other MCP servers.

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 criteria for when to use the tool (bug, feature/data_gap, praise) and when not to use it (if the tool came from a different MCP server, file with that server instead). It also explains the claim_token flow, giving clear operational guidance beyond simple 'use for feedback.'

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

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

Annotations already declare readOnly, openWorld, idempotent, not destructive. Description adds valuable context: data source (CF analytics-engine), no PII, data structure (pack, tool, count), and caching behavior (5min-1h). No contradictions.

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

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

Two concise sentences with a bulleted list of use cases and a note on caching. Every sentence adds value; no wasted words. Front-loaded with high-level purpose.

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

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

Despite no output schema, description clearly states what is returned (top tools, top packs, total call volume) and the data source. Combined with thorough annotations, no gaps remain 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 provides full enum description for 'window'. Description adds extra semantic guidance ('shorter windows surface what's hot right now; longer windows show steady-state demand'), which aids selection beyond the schema's basic description.

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

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

Description clearly states it returns top tools, top packs, and total call volume over configurable windows (24h, 7d, 30d). This distinguishes it from siblings like 'discover_tools' or 'ask_pipeworx', providing a specific verb and resource.

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

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

Explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tools, aligning use case with agent needs) and provides guidance on window selection (short vs. long windows surface different trends). This is exceptional 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 indicate read-only, idempotent, non-destructive. Description adds significant behavioral context: monotonicity checks, partition sum, fill check against live order book, and conditions for skipping trades. No contradictions.

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

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

Description is detailed but well-structured with sections for modes, filters, response, and fill check. Front-loaded with core purpose. Some redundancy, but acceptable given complexity.

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

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

Comprehensive for a complex analytical tool with no required parameters. Covers algorithmic logic, edge cases (placeholder slugs, low similarity), output response structure, and references sibling tool for custom sizing. No output schema but response is 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 descriptions cover both parameters, but the tool description adds substantial detail (event slug format, topic as seed question, scanning behavior). Adds value beyond schema.

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

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

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

Explicit guidance on when to use each mode: no args for trending, event for specific market, topic for cross-event. Also explains semantic anchor, partition filter, fill check, and when not to trade (realizable_edge_pp <= 0).

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

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

The description extensively details behavior: three model families, edge calculation, Kelly sizing, liquidity/spread filters, response structure with diagnostics, and caching. It does not contradict annotations; it adds significant context beyond their readOnlyHint, idempotentHint, and destructiveHint values.

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 and detailed but front-loaded with the primary purpose. While structured with sections, it contains verbose technical details that could be condensed. It earns its place but could be more concise.

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

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

Given the complexity (9 parameters, no output schema), the description comprehensively covers the response structure, segment explanations, filter behavior, and diagnostics. It explains why segments may be empty and how knobs affect results, leaving minimal gaps.

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

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

Schema coverage is 100%, so description adds less burden but still provides meaningful semantic context, such as explaining that min_kelly does not filter partition arbs and that min_partition_leg_kelly applies per-leg. This adds value beyond the schema descriptions.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market prices, targeting the use case 'what should I bet on today'. It uses specific verbs and resources, and the purpose is distinct from sibling tools despite not explicitly contrasting them.

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

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

The description implies usage for discovering betting opportunities and explains filtering knobs, but does not provide explicit guidance on when not to use this tool or how it compares to alternatives like polymarket_arbitrage. Usage context is implied rather than explicit.

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 (readOnly, openWorld, idempotent, non-destructive), the description adds rich behavioral info: history limited by 60-day TTL, snapshots written on cache miss, decay computed from daily closes, and detailed 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 front-loaded with purpose and key insight, then details response structure and limits. Every sentence is informative, though it is somewhat dense. Could be slightly more structured but remains 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?

Despite no output schema, the description comprehensively explains the response (tracked with fields, expired with lifespan, snapshot dates) and limitations (TTL, gaps). For a tool with 2 parameters and complex output, this is 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 descriptions for both parameters. The description supplements with default values and explains the meaning of 'window' as snapshot family, adding value beyond the schema.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots. It distinguishes itself from siblings like polymarket_edges by focusing on historical tracking rather than current snapshot.

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 context on when to use it (to answer 'how long has this edge existed and is it shrinking?') and implies its distinction from snapshot tools. No explicit when-not or 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 indicate readOnly=true, idempotent=true, no destructive effect. Description confirms it is a check, details the process (walks ladder, returns verdict) and warns of forced directional risk. No contradiction, and adds rich 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?

Description is dense and informative, properly front-loaded with purpose. While each sentence is justified, the length could be slightly reduced without losing clarity. Still, structure is logical with clear mode separation.

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 effectively lists all return fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.) and explains edge cases (thin legs, forced directional risk). Covers all necessary context for correct tool usage and interpretation.

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

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

Schema coverage is 100%, but description adds significant context: explains 'market' is single-market mode, 'event' is basket mode, clarifies meaning of 'size_usd' for buys vs sells and basket vs single-market, and provides defaults and clamps. Greatly aids correct parameter usage.

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 a realizable-vs-theoretical edge check against live order book depth. Differentiates between single-market and basket modes, and explicitly distinguishes from sibling tools polymarket_arbitrage and polymarket_edges by stating 'USE THIS before acting on any 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?

Explicitly advises when to use: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. Explains the rationale: theoretical overround may not be capturable and partial fills create directional risk.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral details: two operating modes, response structure with raw probabilities and spreads, compatibility warnings for non-equivalent bet shapes or semantically unrelated events, temporal alignment checks, and counters for skipped comparisons. 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 relatively long but well-organized: it starts with purpose, then explains modes, response, and safety fields. Every sentence adds value, though slight trimming could improve conciseness without losing 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?

Despite no output schema, the description details the response structure (leg-by-leg prices, top_spreads_pp) and explains all safety fields (compatibility_warning, temporal_alignment, skipped counters) thoroughly. It covers edge cases like non-equivalent bet shapes and temporal misalignment, making the tool self-contained.

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

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

Schema coverage is 100%; the description adds meaning beyond schema by explaining the 'topic' mode with explicit examples of shortcuts, and how kalshi_event_ticker/polymarket_event_slug override the mapped sides. This helps the agent understand parameter interactions and usage.

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

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

The description clearly states the tool's purpose: computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes between two modes (topic shortcuts and explicit tickers) and explains the condition for meaningful spreads, differentiating it from siblings 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 explicitly explains when to use each mode ('topic' for pre-mapped macros, explicit tickers for custom pairings) and warns that most pre-mapped topics return compatibility warnings, guiding the agent on realistic expectations. It also details the safety fields that indicate when spreads are not valid.

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 (readOnly, idempotent), adds scoping detail (by identifier) and list behavior, 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?

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

No output schema but description implies return value or list; annotations cover safety; sufficient for a simple read 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% and description repeats the schema's parameter explanation, adding no extra semantics.

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 previously saved value or lists all keys, distinguishing it from sibling tools 'remember' and 'forget'.

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

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

Explicitly says when to use (look up stored context) and when to omit key (list all keys), hints at pairing with remember/forget, but doesn't state when not to use.

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

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

The description discloses that mark_read flags events as read, affecting subsequent calls, which supplements the annotations (readOnlyHint, idempotentHint). It details return fields (source, citation_uri, payload) and the effect of mark_read, providing comprehensive behavioral 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 a single paragraph of five sentences, efficiently conveying purpose, parameters, behavior, and alternatives. It is front-loaded with the core function but could be slightly more structured with bullet points.

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 annotations covering read-only/idempotent behavior and a complete parameter schema, the description adds necessary return format details and alternative access method. No output schema exists, but the return contents are described. Minor gaps like error handling or rate limits are acceptable for 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?

All 5 parameters have schema descriptions (100% coverage), but the description adds context: it explains how type and since filter results, that limit controls max events, and crucially that mark_read marks returned events as read. This goes beyond the 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 it pulls fired events from a subscription feed and returns recent alerts. It distinguishes itself from sibling tools like list_subscriptions and subscribe by focusing on event retrieval with specific payload details.

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

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

The description explains when to use filters (type, since) and the mark_read flag, and notes that polling works fine. It mentions an alternative endpoint but does not explicitly contrast with sibling tools or state when not to use it.

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

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

Description adds significant context beyond readOnly/idempotent annotations: fan-out to SEC, GDELT, GNews, USPTO; failure modes; rate-limit handling. 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?

Packed with information, front-loaded with query examples. Some redundancy but every sentence adds value. Could be slightly more concise but still effective.

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

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

Covers input, sources, fallback, failure modes, and output structure. No output schema, but description adequately explains return format. Could mention pagination or limits, but sufficient for a tool of this complexity.

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

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

Schema covers all three parameters with descriptions. The description adds valuable details: examples for 'since' (ISO and relative), ticker/CIK guidance for 'value', and enum constraint for 'type'.

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

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

The description uses specific verbs and resources: 'returns structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. It distinguishes from the sibling tool 'entity_profile' by explicitly stating 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?

Provides explicit when-to-use guidance with example queries, fallback behavior (GDELT→GNews), window format details, and a clear alternative ('Use entity_profile instead when you want the static profile').

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 cover idempotency (write but not destructive). Description adds scoping by identifier and retention periods (persistent for authenticated, 24h for anonymous). 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?

Three sentences front-load purpose, then usage, then behavioral details. No waste, every sentence adds unique 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 simple key-value store with 2 required params, the description covers persistence, scoping, retention, and pairing with related tools. Complete guidance.

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

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

Schema already provides 100% coverage with descriptions. Description adds naming conventions and value examples but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool saves data for reuse across conversations/sessions, gives concrete examples (ticker, address, preference), and distinguishes siblings by mentioning pairing with recall and forget.

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

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

Explicitly says when to use ('when you discover something worth carrying forward'), how it scopes by identifier, and pairs with recall/forget. Provides clear context without ambiguity.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description adds rich behavioral details: graceful degradation of LEI/FIGI enrichment, explicit labeling of sources, unresolved identifiers listed under `unresolved`, and cascading internal lookups. These are valuable operational traits not otherwise disclosed.

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

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

Though long, the description is well-structured and every sentence earns its place: it opens with concrete examples, states the purpose clearly, details supported types, explains failure behavior, and ends with a benefit. It is dense but organized, making effective use of space.

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

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

With no output schema, the description robustly explains return values for each type, including fallback behavior and explicit unresolved handling. It also accounts for graceful degradation and cascading, making it complete for agent decision-making.

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

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

The schema already covers both parameters with clear descriptions, and the description adds meaning by explaining what each type returns (e.g., company resolves CIK/ticker/LEI/FIGI; drug resolves RxCUI/ingredient/brand) and accepted input variants. This goes beyond the schema's baseline.

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

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

The description explicitly states the tool resolves user-spoken names to canonical identifiers, with specific verbs and resources (ticker, CIK, LEI, RxCUI). It clearly distinguishes itself as the first step when needing an ID, setting it apart from sibling tools like entity_profile or compare_entities.

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

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

It gives clear guidance: 'Use FIRST whenever you have a name but need an ID.' This provides explicit when-to-use context. However, it does not name alternative tools or state explicit exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnly and idempotent behavior. The description adds context: it probes each entity with 'ai_visibility_check', ranks results, and returns scores, confidence, and signal density. This exceeds annotation coverage.

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

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

The description is three sentences, no redundancy, front-loaded with the main purpose, then how it works, then an example use case. 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 no output schema, the description explains the return format (ranked list with score, confidence, signal density). It covers the main use case, the process, and parameter roles. Minor missing: no mention of rate limits or error handling, but not critical.

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

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

Schema has 100% description coverage. The description adds meaning by explaining that the first entity is treated as the subject, that context is shared across probes, and that the tool ranks by score. This enriches understanding beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities, using 'ai_visibility_check' internally, and ranks them. It distinguishes itself from the sibling 'ai_visibility_check' by focusing on side-by-side comparison.

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

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

The description explicitly states it's useful for competitive AI-marketing audits and implies when to use (comparing multiple entities). It references the sibling tool indirectly by mentioning the internal use of 'ai_visibility_check', but lacks an explicit 'when not to use' statement.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds critical behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts. 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 detailed and well-structured, starting with the composite check, then data sources, usage guidance, ecosystem constraints, and graceful degradation. Slightly verbose but every sentence adds value; front-loaded effectively.

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 comprehensively lists return fields (summary block, advisories, links, alternatives) and explains partial failure behavior. All necessary context for correct invocation is present.

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

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

Schema description coverage is 100% with clear descriptions. The description adds context: version defaults to latest, scoped packages accepted, and example formats like '18.3.1' and '@types/node'. This enhances the schema.

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

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

The description clearly states the tool's purpose: a composite check for npm packages using deps.dev and bundlephobia. It specifies the verb (scan/check), resource (npm dependency), and distinguishes from siblings by being npm-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?

Provides explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small"...' and when-not-to-use: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This effectively advises on alternatives.

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

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

Annotations already declare safe, idempotent, read-only behavior. The description adds technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap, and truncation flagging. This provides beyond-annotation 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?

Only four sentences, all substantive. Purpose is front-loaded, each sentence adds new information (pairing, algorithm, offsets, limits). No filler or redundancy.

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

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

Despite no output schema, the description explains return values ('top-N passages with character offsets and similarity scores'), usage context, limits, and pairing. Covers all necessary aspects for a 3-param 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?

Input schema has 100% coverage, so baseline is 3. The description repeats schema info for text and limit but adds helpful query examples ('supply-chain risk', 'fiscal year 2024 revenue'). This adds marginal value beyond schema.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' clearly specifying the action and target. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and implying it's for records too large for prompts. No tautology; highly 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?

The description explicitly states when to use ('record is too big to cram into the prompt') and mentions a complementary tool (ask_pipeworx_grounded). It does not list alternative search_tools or explicitly state when not to use, but context is clear.

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

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

Annotations indicate idempotentHint=true, readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds significant context: return value, delivery channels (always-on feed, optional email/sms/webhook), rate limits (10/day sms cap), and prerequisite (OAuth account). This enriches the behavioral understanding 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?

Although lengthy, the description is well-structured and front-loaded: first sentence gives core purpose, then prerequisites, types, and delivery channels. Every sentence adds value, and the information is organized logically without redundancy.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description covers all necessary aspects: type-specific filters, delivery options, prerequisites, rate limits, and return value. It is self-contained and provides enough information for an agent to use the tool correctly.

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

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

Schema coverage is 100%, and the description goes beyond schema by explaining each type's purpose and parameters in detail (e.g., sec_8k item codes meaning, polymarket_edge topic examples). It also clarifies delivery channel nuances like webhook signing secret and phone verification. This substantially enhances parameter understanding.

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

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

The description clearly states the verb 'Create' and the resource 'proactive monitoring subscription', and specifies the return value 'new subscription id'. It differentiates from sibling tools like 'unsubscribe' and 'list_subscriptions' by detailing the subscription creation and its features.

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 prerequisites (Pipeworx OAuth account) and delivery channel specifics, but does not explicitly contrast with sibling tools like 'list_subscriptions' for listing or 'unsubscribe' for deletion. The usage context is clear but lacks explicit when-not-to-use guidance.

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

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

Annotations already mark it as read-only and idempotent. The description adds behavioral detail: returns question examples with tool shapes, drawn from live catalog. 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 somewhat lengthy but well-structured, front-loaded with example queries. Every sentence adds value, though it could be slightly more concise.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers what the tool returns (category-bucketed questions with tool shapes) and how to use it in different modes. No gaps.

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

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

Schema coverage is 100% with a description for the topic parameter. The tool description adds examples of valid focus areas and explains how omitting the parameter gives a full spread, enhancing the schema's minimal description.

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

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

The description clearly states the tool returns category-bucketed example questions with exact tool+argument shapes. It positions itself as the onboarding entry point, distinguishing from sibling tools like discover_tools and ask_pipeworx.

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

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

Explicitly says to use this tool first when unsure what Pipeworx can do, and describes when to omit or use the topic argument. Provides clear guidance on entry-point usage.

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

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

Description adds behavioral context beyond annotations: deactivation rather than deletion, ownership enforcement. Annotations already indicate non-destructive mutation, and description aligns without contradiction.

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

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

Two concise sentences front-loaded with key info: action, ownership, behavioral details. No wasted words.

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

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

For a simple single-parameter cancellation tool with no output schema, description covers purpose, constraints, and behavior comprehensively.

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

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

Schema has 100% description coverage with clear description of 'id' parameter. Description does not add extra detail beyond schema, which is acceptable.

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 'Cancel a subscription by id' with specific verb and resource. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement and that only own subscriptions can be cancelled. Provides context that row is deactivated, not deleted, preserving history. Lacks explicit alternatives but sufficient.

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

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

Despite annotations already providing readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds substantial behavioral context: the two-pipeline routing (SEC EDGAR/XBRL vs grounded), the verdict set, citation format, and a critical warning that could_not_verify means the check did not happen and must not be interpreted as evidence. This goes well beyond the annotations' safety hints.

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

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

The description is long but information-dense; every sentence contributes: examples, routing logic, return value details, and the crucial error semantic. It could be better structured with bullet points for the verdict list, but the flow is logical and no part feels redundant.

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

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

With no output schema, the description must convey the response shape, and it does: verdict values, actual value with pipeworx:// citation, reasoning, and error fields. It also covers the unsupported vs could_not_verify distinction. Minor gaps like the exact structure of verification_error are not critical for basic 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?

Input schema covers 100% of the 2 parameters, so baseline is 3. The description enriches this with a concrete example for claim and explains tolerance_pct's default behavior and its purpose for hallucination detection, adding value beyond the schema's basic descriptions.

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

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

The description is explicit: 'natural-language claim verification against authoritative sources' and enumerates common phrasings ('fact check', 'verify the claim that…'). It clearly distinguishes the tool from siblings like deep_research by framing it as a direct true/false verification of user statements, and mentions it replaces 4–6 sequential calls, reinforcing its unique role.

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

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

The description gives a clear trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing for company-financial vs. other claims, but does not explicitly name alternative tools or state when NOT to use it, so it lacks full when-not guidance.

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