The Committee

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

Annotations already cover read-only, open-world, idempotent, and non-destructive traits, and the description adds important behavioral context: the default model (Workers AI Llama-3.3-70b, free), the BYO-key mechanism for Anthropic, and the cost implication ('you pay Anthropic directly'). It also discloses the return format (per-model score, confidence, signals, raw_response, combined view), which is especially valuable since no output schema is provided.

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

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

The description is three sentences, front-loaded with the core purpose. Every sentence carries distinct value: the purpose and scoring, the model/cost details, and the return format plus use cases. 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 the lack of an output schema, the description compensates by explicitly listing the return structure and per-model fields. It covers purpose, default behavior, optional components, cost implications, and use cases. All four parameters are mentioned or contextualized, making this a complete and self-sufficient description for a moderately complex tool.

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

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

Schema coverage is 100%, so the baseline sits at 3, but the description adds meaningful parameter semantics beyond the schema. It clarifies that `_apiKey` is only needed if 'anthropic' is in models, notes the default model when `models` is omitted, and gives concrete examples for the `entity` parameter. This extra context helps the agent understand parameter relationships.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility 0-100 per model. It uses specific verbs and resources, and the mention of 'AI-marketing audits, pre-launch brand checks, competitive monitoring' distinguishes it from generic ask-type sibling tools.

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

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

The description provides clear usage context by listing concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). However, it does not explicitly mention when not to use it or name alternatives among siblings, so it stops short of full guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds behavioral context: it routes to many tools, returns structured answers with pipeworx:// citations, works on every tier, and is a single fast call. It does not disclose failure handling or ambiguity behavior, but the combination of annotations and description is strong.

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

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

The description is long but well-organized: it starts with a strong 'PREFER OVER WEB SEARCH' directive, then explains mechanics, gives examples, and clarifies alternative tools. Some redundancy exists (e.g., repeating the default entry point), but the structure is front-loaded and every section serves a 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?

For a routing tool with no output schema, the description covers what the agent needs: scope, sources, output format (citations), when to escalate to alternatives, and example queries. It even mentions limitations (multi-part questions go to deep_research) and operational characteristics (one fast call, all tiers).

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

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

Schema coverage is 100%—all six parameters are documented as aliases for the natural-language question. The description provides general examples but no per-parameter details beyond what the schema already states. Baseline 3 applies because the schema fully covers parameter 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's purpose with specific action and resource: it routes questions to one of 5,529 tools across 1,455 verified sources and returns structured answers with citation URIs. It distinguishes itself from sibling tools (ask_pipeworx_grounded, deep_research) by explicitly comparing use cases.

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

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

Provides explicit when-to-use guidance as the default entry point for factual questions, including trigger phrases and examples. It also gives clear exclusions: use ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions, and notes it is preferred over web search.

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, etc.), the description discloses that the router is a fully functional experimental edge with live candidate routing, that no candidate is currently active (so it matches ask_pipeworx exactly), and that results are compared against the stable router. This is rich behavioral context not available in structured fields.

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

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

The description is concise yet comprehensive, using three sentences to cover the beta nature, current status, usage, and fallback behavior. Each sentence adds value with no redundancy, and the key information is front-loaded.

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

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

For a beta variant with subtle differences, the description fully explains what the tool does, its current equivalence, when to use it, and how results are evaluated. It also clarifies that there is no separate fallback, making it complete for the agent's decision-making. No output schema is needed because the response shape is explicitly stated as matching the stable 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?

The schema covers 100% of the parameters with detailed descriptions, including the 'question' field and its aliases. The description does not add parameter-level details, but the schema already provides full semantics, so the baseline score of 3 is appropriate.

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

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

The description precisely states that this is a beta version of ask_pipeworx with an identical universal router (same 5,529 tools, arguments, and response shape), explicitly distinguishing it from the stable sibling. It clearly identifies the tool as a working router rather than a stub.

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 says 'Use it exactly like ask_pipeworx when you want the newest routing,' which explicitly indicates when to use it. It also contrasts with the stable ask_pipeworx by explaining the experimental nature and that results are compared for merges, implying the alternative for stable use. It lacks an explicit 'when not to use' statement but provides sufficient context.

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

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

Beyond the readOnly/idempotent/openWorld annotations, it discloses the refusal mechanism with specific refusal_reason values, the structured return shape, and the 'uses ONLY the tool result' constraint. No contradiction with annotations; fully transparent about failure modes.

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

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

The description is dense but well-structured: purpose, mechanism, return/refusal format, usage guidance, and cost note. Every sentence adds value, with the most critical info (grounded, high-stakes) front-loaded.

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

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

Given no output schema, the description fully explains return values and refusal reasons. It covers when to use, trade-offs, and behavioral guarantees. No significant gaps for an AI agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and all parameters are aliases for 'question', which the schema already explains. The description adds no additional parameter semantics beyond reinforcing natural language input, so baseline 3 applies.

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

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

The description clearly states the tool's function: a hallucination-resistant answer mode that uses tool results exclusively for answers. It explicitly contrasts with ask_pipeworx, distinguishing itself as the grounded variant.

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 (high-stakes reads where answers are quoted/cited/acted on) and when-not-to-use (casual lookups, recommending ask_pipeworx instead). Also notes the cost trade-off (one extra LLM call), giving clear selection criteria.

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

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

Despite having annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description goes far beyond them: it describes resolver contract fields (market_match_confidence, alternatives, suggestions), safety short-circuit statuses (low_confidence_match, market_closed_or_inactive), tradeability flags, news fallback behavior, and cancellation-rule risk. This gives the agent essential behavioral context for safely trusting/sizing results.

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

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

The description is long but well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, SAFETY, RESOLUTION-RULE RISK). Every section adds operational detail an agent needs, though a few examples are arguably redundant. It's not a model of conciseness, but the structure earns it a 4.

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 and significant complexity, this description is remarkably complete. It tells the agent what to inspect before trusting analysis, how to handle low-confidence matches, what statuses to expect, how to interpret parent_event partitions, and how to assess cancellation-rules risk. This is sufficient to use the tool correctly without additional documentation.

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

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

The input schema already describes all three parameters with 100% coverage, including examples, defaults, and effect of include_raw. The description adds color about fan-out categories and response shapes, but does not materially enhance the per-parameter meaning beyond what the schema provides. Therefore the baseline of 3 applies.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling tools like polymarket_edges or validate_claim by listing use cases ('should I bet on X', 'what does the data say about Y') and describing its unique fan-out/resolution behavior.

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

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

The description explicitly states when to use the tool ('Use for "should I bet on X"...'), but it does not explicitly name alternatives or say when NOT to use it. Given the large sibling toolset, an explicit exclusion or pointer to alternatives would elevate this to 5. Still, the stated use cases are clear and actionable.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds rich behavioral detail: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), correct handling of off-calendar fiscal years, sorting by primary metric so 'largest' reads off the top, and return format (paired data + citation URIs). This gives the agent a comprehensive understanding of what the tool does and how it behaves, without contradicting annotations.

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

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

The description is compact yet densely informative. It opens with natural language examples, states the core function and preference rule, then details type-specific behaviors and output. Every sentence contributes value, and the structure guides the reader from overview to specifics 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 moderate complexity (two entity types, up to 5 items) and the absence of an output schema, the description adequately covers return values ('paired data + pipeworx:// citation URIs per entity'), sorting behavior, and data sources. It also notes fiscal year handling, which is non-obvious. No critical information for selection or invocation is missing.

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

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

The schema already provides 100% coverage with clear descriptions for both parameters. The description adds further semantic value by explaining what each type pulls (e.g., 'latest 10-K revenue + net income + cash + long-term debt' for companies) and providing concrete examples for values (e.g., ['AAPL','MSFT']). While not exhaustive, 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's function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It provides concrete trigger phrases, identifies the entity types, and distinguishes it from sequential single-pack lookups. This goes beyond a vague statement and effectively differentiates the tool from siblings like entity_profile.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving a clear directive for when to use this tool. It also explains the two entity types and their respective data sources, which guides selection. However, it does not explicitly mention alternative tools (e.g., entity_profile) or state when not to use it, so it falls short of a perfect score.

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 discloses account requirements and paid plan, expected latency (15-60s, up to ~90s), the gaps[] behavior (never invented), how depth affects hop/recovery, and that citations are always fetchable. 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 long but information-dense with clear front-loading (account requirement first). Every sentence adds behavioral or usage value, though it could be tightened. The structure flows from requirements to use cases to limitations to output details.

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

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

Given the tool's complexity, no output schema, and rich annotations, the description covers auth, pricing, latency, alternatives, input expectations, output structure (findings packet, gaps, contradictions), and citation semantics. It is fully sufficient for an agent to select and invoke correctly.

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

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

The input schema already describes both parameters with 100% coverage. The description adds extra meaning by explaining the effect of depth values ('standard' re-angles unanswered gaps; 'thorough' chases leads) and emphasizing that broad/multi-part natural language questions are acceptable. This goes 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 clearly identifies the tool as multi-source research over Pipeworx's 1455 structured data sources, decomposing questions into facets and routing to tools in parallel. This distinguishes it from siblings like ask_pipeworx and bet_research, and mentions specific resource types (SEC filings, FRED, FDA, etc.).

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and direct alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx.' Also explains depth tiers and when each is appropriate.

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 establish safety (read-only, idempotent, non-destructive). The description adds meaningful behavioral context: results include top-N tools with names, descriptions, and full schemas, ready to call directly with no second schema lookup. This is exactly the kind of beyond-annotation disclosure that adds value.

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

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

The description is somewhat lengthy due to the domain list, but every sentence contributes: purpose, usage context, return format, and positioning as a first call. The front-loaded opening sentence makes it scannable, and the domain enumeration is genuinely informative even if it adds length.

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

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

For a discovery meta-tool with no output schema, the description fully specifies what the agent will receive (top-N tools, names, descriptions, schemas, examples) and the intended orchestration pattern ('Call this FIRST'). Combined with rich annotations and full schema coverage, no critical information is missing for effective tool selection and invocation.

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

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

Schema coverage is 100%, with query and all aliases fully described in the input schema, including the limit parameter. The description's mention of 'top-N' and 'ready to call' adds context but does not clarify individual parameter semantics beyond what the schema already provides. The baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource ('Find tools') and immediately clarifies the use case ('browse, search, look up, or discover what tools exist'). It lists concrete domains and states that it returns tool names, descriptions, and full input schemas, distinguishing it clearly from all sibling tools.

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

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

The description explicitly states when to use the tool: 'Use when you need to browse, search, look up, or discover...' and 'Call this FIRST when you have many tools available.' It implies when not to use it ('not just one answer') but does not name specific alternative tools, so it falls short of full when-not/alternatives guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds valuable behavioral context: fans out across multiple sources, describes the patents API sunset with soft-fail behavior, mentions GDELT→GNews fallback, and details return contents such as recent_filings URIs and fundamentals fields.

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

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

The description is dense but well-structured, starting with trigger phrases and examples, then stating the rule to prefer this tool, and finally listing return components and input rules. Every sentence contributes information 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?

Despite having no output schema, the description thoroughly specifies the return structure: cik, company_name, recent_filings with count and URIs, fundamentals with specific fields and ordering, patents, news, and LEI. It also covers edge cases like patent API sunset and name resolution, so the agent has complete expectations.

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

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

Schema description coverage is 100%, with both 'type' and 'value' fully documented including example values and the name-not-supported caveat. The tool description echoes but does not add semantic meaning beyond the schema; baseline 3 is appropriate.

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

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

The description uses specific verbs and resources: 'full cross-source profile of a US public company' with concrete example queries. It clearly distinguishes the tool from siblings by emphasizing a holistic view and explicitly recommending it over chaining single-pack lookups.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also states input constraints and directs name-only users to use resolve_entity first, effectively excluding inappropriate usage.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the core safety profile is covered. The description adds context about clearing sensitive data and focusing on previously stored memories, which is useful beyond annotations. It does not contradict annotations.

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

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

Two sentences, front-loaded with the main action. Every sentence adds value: the first states what it does, the second when and with what 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?

For a simple one-parameter deletion tool, the description covers purpose, usage triggers, and relationships to siblings. It does not explicitly mention return values or missing-key behavior, but the idempotentHint annotation mitigates that gap. Overall, sufficient for effective tool selection.

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 'key' documented as 'Memory key to delete'. The description only repeats 'by key' and adds no additional format, constraints, or examples beyond schema, so the baseline of 3 applies.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from siblings by referencing remember and recall, making its role in the memory toolset obvious.

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 when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. This provides concrete scenarios and implies remember/recall as alternatives for storage/retrieval, giving clear usage guidance.

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

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

Annotations already cover readOnly/idempotent hints, and the description adds useful behavioral context: it fetches the page, extracts content, and emits a text blob. This explains what the tool actually does beyond the annotation flags, without contradicting them.

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

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

The description is compact and front-loaded: first sentence states the core action and output, second sentence provides use cases. No wasted words; 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?

Despite having no output schema, the description clearly specifies the output is 'a single text blob ready to drop at site-root/llms.txt', which fully communicates the return format. The tool's behavior and use cases are adequately covered, making it a complete description for this moderate-complexity tool.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (url and max_links) with descriptions. The tool description does not add extra parameter-level semantics beyond mentioning the default max links and URL example, which are already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with specific details on what it does (fetches page, extracts title/description/key links, emits standard markdown). This specific verb+resource combination distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'). While it doesn't name alternatives or exclusions, the context is clear enough for an agent to select this tool appropriately.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral detail by listing the exact return fields (id, type, params, created_at, last_fired_at, fire_count), which is especially helpful given the absence of an output schema.

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

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

The description is two sentences, front-loaded with the main action, and every clause adds value. It avoids redundancy and is highly scannable.

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

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

For a simple, read-only list tool with one optional parameter and no output schema, the description covers the primary purpose, return structure, and use cases. The annotations handle safety and idempotency, so no critical context is missing.

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

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

The only parameter, include_inactive, is fully documented in the schema with a clear description and default value. The tool description does not add additional parameter info, but with 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'List the caller's active subscriptions' — a specific verb and resource. It also distinguishes this from sibling mutation tools like subscribe and unsubscribe by framing it as a review action.

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: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly ties to common workflows involving sibling tools and gives clear context for when to invoke this tool.

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

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

All annotations are false, so the description carries the full transparency burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), the anonymous claim_token flow, quota impact ('Free; doesn't count against your tool-call quota'), and scope restrictions. This goes far beyond what structured annotations offer.

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 every sentence delivers operational value: scope, when-to-use, content guidance, claim_token flow, rate limit, quota, and roadmap impact. It is front-loaded with the purpose and flows logically, so the length is justified.

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 explains the primary return behavior (claim_token) and the follow-up read path. It covers prerequisites (none, works without account), constraints (rate limit, cross-server exclusion), and outcome (team reads digests, roadmap impact). Highly complete for a feedback tool.

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

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

While schema coverage is 100%, the description adds meaningful semantics: it maps the 'type' enum to concrete scenarios, provides a usage example for claim_token (`pipeworx_feedback({claim_token:"pwfb_…"})`), and adds content constraints like 'don't paste the end-user's prompt' for message. This enriches parameter 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates feedback categories (bug, feature/data_gap, praise) and clearly distinguishes this tool from sibling research/query tools by being the only feedback mechanism.

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

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

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection… file it with that server instead.' 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds valuable context: it is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. This goes well beyond the structured annotations and sets clear expectations about freshness and privacy.

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

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

The description is well-structured and efficient: a one-sentence summary, a list of concrete use cases, and a brief note on data provenance and caching. Each sentence earns its place, and the bullet-like structure aids scanning without unnecessary verbosity.

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

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

Given the tool's simplicity (one optional parameter, no nested objects) and strong annotations, the description covers all essential aspects: return contents ('top tools, top packs, total call volume'), output shape ('(pack, tool, count)'), data source, caching, and privacy. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for the single 'window' parameter, and the schema already explains the meaning of each window option. The description repeats the window values but adds no new parameter-specific semantics; the caching detail is behavioral rather than parameter-level, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb ('Returns') and resource ('top tools, top packs, and total call volume'), and opens with a concrete question ('What other AI agents are calling on Pipeworx right now'). This distinguishes it from siblings like discover_tools, which focus on discovery rather than aggregated usage trends.

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

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

The description provides explicit use cases ('Useful for: ...'), including discovering hot data sources, confirming canonical choices, and aligning with agent needs. However, it does not explicitly mention when not to use it or name alternative sibling tools, 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?

The description richly discloses behaviors beyond the readOnly/openWorld/idempotent annotations. It details the computational checks (monotonicity, partition-sum), thresholds (>3pp, ≥0.30 Jaccard, >20% placeholder), the fill check against CLOB depth, and edge-case returns (null arb signal). No contradiction with annotations.

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

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

The description is lengthy (~350 words) but well-structured with labeled segments (SEMANTIC ANCHOR, PARTITION FILTER, RESPONSE, FILL CHECK). It front-loads the core purpose in the first sentence. However, some redundancy exists in re-explaining the event/topic modes in detail after introducing them earlier. It could be slightly tightened, but it is organized and information-dense.

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 thoroughly explains return values: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and event-mode partition_check fields. It also covers edge cases like placeholder-filtered null signals and fill-check failure. For a tool this complex, the description is remarkably 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?

Even though the schema already describes both parameters with 100% coverage, the description adds significant semantics: event mode 'walks child markets, checks date-axis/threshold-axis ordering AND computes the partition_check,' while topic mode 'searches related events, flattens markets, runs the comparator on the union.' It also provides concrete examples, enriching beyond the schema.

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

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

The description clearly states the tool's function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the resource (Polymarket) and the action (find arbitrage), and distinguishes its three invocation modes (trending_scan, event, topic) from each other and from sibling tools like polymarket_fill_risk which is mentioned as the alternative for custom sizing.

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

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

Provides explicit usage instructions: 'Call with NO args for a trending_scan...; pass event for...; or topic for...' It also states when to prefer event vs topic modes, and explicitly directs 'For custom sizing use polymarket_fill_risk.' The fill check section also tells the agent when not to trade. This is exemplary guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral context beyond that: "Cached 1h at the KV level keyed on all knobs," the "rare-by-design" nature of concentrated longshots with explicit gate values, the Fed disclaimer about unreliable signals, and the "24h-move warning" that the edge may already be priced in. This gives agents a rich understanding of how the tool behaves and its limitations.

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 its core purpose in the first sentence, then each subsequent section delivers dense, non-redundant operational detail—model families, response structure, per-opportunity fields, filters, and caching. While long, every sentence earns its place for a tool of this complexity, and there is no filler or repetition of schema 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?

With no output schema, the description fully documents the response shape: "RESPONSE TOP-LEVEL: by_segment{...}, fed_candidates/fed_note..., and _diagnostics{...}" plus the per-opportunity fields like edge_pp_net, kelly_fraction, liquidity, and the 24h warning. It also explains why segments can be empty (top-N stale, gates, knobs), making the tool actionable even in edge cases.

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% parameter coverage with detailed descriptions for all 9 parameters, so the baseline is 3. The description adds extra semantics by explaining how knobs interact: "TRADEABLE-EDGE KNOBS: min_liquidity / max_spread_pp drop opportunities where edge isn't realizable" and "min_kelly never filters them" for partitions. It goes beyond the schema's per-parameter text, earning a 4.

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

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

The first sentence states a specific verb+resource+scope: "Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price." It also distinguishes itself from siblings by explicitly targeting the "what should I bet on today" discovery use case, avoiding the need to page hundreds of markets, which separates it from tools like polymarket_arbitrage or polymarket_fill_risk.

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

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

The description clearly frames when to use the tool: "Built for 'what should I bet on today' — agents discover opportunities without paging hundreds of markets." It also provides practical guidance on knobs like min_liquidity and max_spread_pp to drop unrealizable edges. However, it does not explicitly name alternatives or state when not to use this tool versus related siblings, so it falls short of a 5.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses the full response structure, the distinction between tracked and expired opportunities, snapshot-gap causes, TTL limits, and that decay is computed from daily closes on |edge_pp_net|. This is extensive behavioral detail.

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

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

The description is long but well-organized into purpose, args, response, and limits. It is front-loaded with the core question and every sentence provides necessary information. The length is justified by the tool's complexity and the absence of an output schema.

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

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

No output schema exists, so the description compensates by detailing the response objects (tracked, expired, snapshot_dates), edge sign conventions, trend categories, and practical limitations. It covers edge cases like cache-miss gaps and TTL, making it fully actionable.

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 describes both parameters with defaults, clamps, and window values (100% coverage). The description merely restates 'days (lookback, default 14, max 30)' and 'window (snapshot family, default 1wk)' without adding new meaning, so the baseline 3 applies.

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

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

The description opens with 'Edge persistence and decay telemetry' and explicitly answers the question 'how long has this edge existed and is it shrinking?' This is a specific verb+resource that distinguishes it from siblings like polymarket_edges, which focus on current edge computation.

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 strong context by stating the exact use case (determining edge age and decay) and implies when to use it for historical analysis. However, it does not explicitly name alternatives or state when NOT to use it, so it misses the full 'when vs alternatives' clarity.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description fully aligns with these. It goes far beyond annotations by disclosing how the tool walks the order book, what fields it returns (e.g., slippage_pp, shares_filled, capture_ratio), and the specific risk of partial basket fills converting an arb into an unhedged directional position. This is rich behavioral context that directly informs the agent of consequences.

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

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

The description is long but every sentence earns its place. It is structured by mode (single-market/basket), enumerates exact return fields, and ends with a usage directive. Despite its length, it is front-loaded with the core purpose and never meanders. The density is justified by the complexity of the tool.

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

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

With no output schema, the description carries the full burden of explaining return values and system behavior. It does so exhaustively: for single-market it lists top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and verdict; for basket it lists theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, and forced_directional_risk. It also covers mode selection, defaults, and clamping, making the description self-sufficient for correct 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?

Although the schema has 100% description coverage, the tool description adds substantial meaning. It explains the two parameter modes ('SINGLE-MARKET' vs 'BASKET'), the interpretation of size_usd in each mode ('max spend on buys, target proceeds on sells' vs 'settlement notional S'), and the auto-detection of side in basket mode. This is exactly the kind of semantic enrichment that helps an agent choose correct values.

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, precise statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from siblings by naming polymarket_arbitrage and polymarket_edges and positioning itself as the pre-trade risk check. The single-market vs basket modes are explicitly described, making the tool's function 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 gives explicit when-to-use instructions: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It further explains why—theoretical edge on thin books is not capturable and partial basket fills create unhedged directional risk—thus providing both the trigger and the rationale.

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?

Even though annotations already mark the tool as read-only, idempotent, and non-destructive, the description goes far beyond by detailing compatibility_warning conditions, temporal alignment checks, skipped_cross_type/subtype counters, and scenarios where spreads are mathematically meaningless. This rich behavioral disclosure fully informs the agent of edge cases.

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

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

The description is dense but well-structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS). It is longer than typical but every section provides essential operational detail. The structure helps navigation, though it could be tightened without losing value.

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

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

With no output schema, the description carries full responsibility for explaining the response contents, which it does thoroughly (leg-by-leg prices, matched spreads, compatibility warnings, temporal alignment). It also addresses the tool's complexity (3 optional parameters, edge cases) completely, ensuring the agent knows what to expect.

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

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

The schema already documents all three parameters with descriptions, but the description adds significant meaning by explaining the two modes, how 'topic' maps to pre-mapped shortcuts, and how explicit tickers override the topic-mapped sides. It also clarifies the difference between topic and explicit modes, going well 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 clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, and distinguishes it from sibling tools by emphasizing the cross-venue comparison. It also explicitly differentiates the two modes (topic shortcuts vs explicit tickers), making the tool's purpose unambiguous.

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

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

The description provides clear context on when to use the tool (to compare equivalent outcomes across venues) and warns that most pre-mapped topics currently return compatibility_warning, implying limited tradeability. However, it does not explicitly mention alternative tools or state 'use this instead of X', so it stops short of 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.

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

Annotations already provide read-only, idempotent, and non-destructive hints. The description adds meaningful behavioral context: it is scoped to an identifier (anonymous IP, BYO key hash, account ID), and omitting the key lists all saved keys. This goes beyond annotations without contradicting them.

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

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

The description is concise (four sentences) and front-loaded with the primary purpose. Every sentence contributes value: function definition, use case, scoping context, and sibling relationships. No filler or redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, scoping, and relationships to related tools. It explains the listing behavior when key is omitted and is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for the single parameter, and the schema's description already states 'Memory key to retrieve (omit to list all keys).' The tool description repeats this behavior but does not add additional parameter-level detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function with specific verbs: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It distinguishes itself from sibling tools by explicitly referencing remember and forget, making it unambiguous.

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

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

The description explains when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also provides relational guidance ('Pair with remember to save, forget to delete'), though it doesn't explicitly state exclusions or alternative tools beyond these siblings.

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

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

Annotations declare readOnlyHint=true, but the description states that setting mark_read:true flags events read and changes which events future calls return, implying a persistent state mutation. This directly contradicts the read-only annotation. No other behavioral details like auth or rate limits are provided.

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

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

The description is four sentences, each earning its place: purpose, return payload, filtering parameters, mark_read behavior, and alternative access. It is front-loaded and free of 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 absence of an output schema, the description helpfully describes the return payload. It covers filtering, side effects, polling suitability, and an alternative endpoint. Some parameters like limit and unread_only are not mentioned in prose, but the schema fully covers them. The annotation contradiction slightly undermines completeness.

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%, providing baseline context. The description adds meaning beyond schema by giving example usage for type ('sec_8k') and since (ISO timestamp), and explains the effect of mark_read on subsequent calls. This enriches 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 uses a specific verb 'Pull' and identifies the resource as 'fired events from your subscription feed,' clearly distinguishing it from sibling tools like list_subscriptions and recent_changes. It also specifies what each alert carries, making the purpose unambiguous.

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

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

The description explains filtering by type and since, the mark_read side effect for successive polls, and explicitly says 'Polls work fine.' It offers an alternative access method via GET URL for scripts/dashboards, but does not explicitly contrast with sibling tools. This is clear usage context, though not full when-to-use vs alternatives.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the multi-source fan-out (SEC EDGAR, GDELT→GNews fallback, USPTO), including fallback conditions (GNews when rate-limited or 5xx) and the PatentsView API sunset that causes a soft-fail. This provides rich 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 dense but not bloated; every clause earns its place. It is front-loaded with user-intent examples, then covers sources, parameters, return shape, and alternatives. Slightly long but efficient given the tool's complexity.

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

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

Despite lacking an output schema, the description fully specifies the return structure (changes[] grouped by source, total_changes, citation URIs), source-specific behaviors, fallback logic, and a known limitation (USPTO soft-fail). It also directs users to entity_profile for static profiles, making the description complete for informed tool selection.

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

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

While schema coverage is 100%, the description enriches parameter meaning by explaining the `since` parameter in detail (ISO vs relative formats with examples) and how it maps to each source's filter (filings since vs. news mentions). It also clarifies acceptable `value` forms beyond the schema's brief note.

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

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

The description clearly defines the tool as a 'change feed for a company in the last N days/weeks/months' with concrete query examples. It explicitly distinguishes itself from entity_profile by noting when to use that sibling instead, making its purpose unambiguous.

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

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

The description provides explicit usage context through query examples and states an alternative: 'Use entity_profile instead when you want the static profile...'. It also explains the window formats and typical monitoring recommendation, giving clear when-to-use guidance.

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

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

The description adds behavioral context beyond annotations: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. This complements the idempotentHint=true annotation, and there is no contradiction with the readOnlyHint=false or destructiveHint=false flags.

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

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

The description is concise, front-loaded with the main action, then usage context, and sibling relationships. Each sentence adds value without redundancy.

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

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

For a simple write tool with two params and no output schema, the description covers what, when, persistence, scoping, TTL, and sibling integration. It is complete enough for an agent to decide when to use it and what to expect.

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 rich parameter descriptions (e.g., key examples and value format). The description mentions key-value pairs but does not add meaning beyond the schema; baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It specifies a concrete action (save) and resource (key-value memory), and distinctly differentiates from siblings by mentioning 'Pair with recall to retrieve later, forget to delete.'

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

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

Explicit usage guidance is provided: 'Use when you discover something worth carrying forward...' and it names alternatives ('Pair with recall to retrieve later, forget to delete'). This also implicitly clarifies when not to use (when you need to retrieve or delete).

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, non-destructive. Description adds valuable behavioral context: identifiers labelled with source, unresolved identifiers explicitly returned under `unresolved`, graceful degradation when GLEIF/OpenFIGI unavailable, and internal cascading through multiple endpoints. No contradiction with annotations.

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

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

Description is long but information-dense and well-structured: starts with query examples, then supported types with details, then fallback behavior. Every sentence earns its place, but the length could be slightly trimmed without losing value.

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

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

Despite no output schema, description covers return contents (identifiers, sources, unresolved list), failure modes (graceful degradation), and internal scope (cascading lookups). For a two-parameter tool with rich behavior, this is highly complete.

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

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

Schema coverage is 100%, so baseline is 3. Description adds examples for both types (ticker, CIK, name; brand or generic), explains what each type returns, and clarifies input formats. This goes beyond schema descriptions to add practical context, though not exhaustive for edge cases.

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 'resolve' and resource 'canonical/official identifiers', clearly distinguishing from siblings like entity_profile or compare_entities. It states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input' and gives concrete query examples, making the purpose unmistakable.

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

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

Provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also mentions replacing 2-3 manual lookups, giving clear context for when to use this tool versus alternatives. No explicit exclusions, but the directive is strong and 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?

Annotations already declare safe read-only/idempotent behavior. The description adds valuable operational detail: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This goes beyond the annotations and fully discloses the tool's behavior.

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

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

Three sentences, front-loaded with the core comparison purpose, then adding mechanistic detail and a concrete use case. No wasted words; every sentence contributes unique 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 having no output schema, the description explicitly states the return structure (ranked list with score, confidence, signal density) and explains the internal probing/ranking behavior. Combined with full schema coverage and annotations, the description fully equips an agent to understand the tool's inputs, outputs, and mechanics.

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 schema already documents each parameter, including that the first entity is the 'subject'. The description adds only marginal color (e.g., 'your brand + N competitors') but does not provide additional semantic depth beyond what the schema already states, so 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 states a specific verb+resource+scope: 'Compare AI visibility across multiple entities side-by-side' and further distinguishes itself from the sibling ai_visibility_check by explicitly mentioning it as the underlying probe and adding ranking/comparison behavior. This makes the tool's purpose unambiguous.

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

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

The description gives a clear use case: 'competitive AI-marketing audits' with an illustrative question, and implies multi-entity scenarios. However, it does not explicitly state when to use an alternative (e.g., ai_visibility_check for a single entity), leaving a minor gap.

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 meaningful behavioral traits: external API fan-out, degradation on partial failures, 5-30s latency for first measurement, and the sources_failed field for timeouts. This adds value over the structured 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 dense but every sentence contributes: purpose, usage, output fields, ecosystem scope, and failure behavior. It is front-loaded with the why and when, though it could be slightly more scannable without semicolons.

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 enumerates the summary block fields, per-advisory details, links, and alternatives. It also covers ecosystem limitations and failure behavior, making it complete for a composite tool that calls external APIs.

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 fully describes both parameters (package name with scoped support, version with default behavior), achieving 100% coverage. The description adds no additional parameter-specific semantics, so it relies on the schema—appropriate for a baseline 3.

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

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

The description opens with a specific composite purpose: determining if an npm package should be added to a project, fanning out to deps.dev and bundlephobia. This clearly distinguishes it from sibling research tools and states the resource and action.

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

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

Explicitly provides usage context: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives an exclusion/alternative: only NPM in v1, with PyPI/Maven/Cargo/Go falling under deps.dev:version directly.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses several important behavioral traits: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K character cap with truncation flagged, and output details including character offsets and similarity scores. This gives the agent a clear model of what the tool does internally and what to expect in results.

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 compact paragraph that front-loads the core purpose first. Each sentence earns its place: purpose, use case, pairing with a sibling, technical details, and limitations. There is no filler or repetition, and the structure flows logically from what to how to when.

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 fully covers what the agent will receive (top-N passages with offsets and scores). It also covers input constraints (cap, truncation), the intended workflow (pairing with ask_pipeworx_grounded), and the problem it solves (context savings). This is complete for a relatively simple tool with well-covered parameters.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining how the text is processed (embeddings, windows, truncation) and that the output includes offsets and scores, which enriches the meaning of 'limit' and 'text' beyond the simple schema descriptions. It also reinforces the purpose of the query parameter with natural-language examples.

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,' which clearly identifies the verb (search), the resource (a fetched record), and the scope (inside that record). It further distinguishes itself from the sibling ask_pipeworx_grounded by positioning search_within as the tool for digging into an already-fetched document while the sibling grounds over the relevant passages.

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

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

The description explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt.' It also gives a concrete alternative and integration path: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document,' which clarifies the intended workflow and exclusion.

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

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

The description goes well beyond the annotations by detailing prerequisites (OAuth account), per-type parameters, delivery channel constraints (SMS verification, 10/day cap), webhook behavior (HMAC signing, one-time secret, auto-disable after 10 failures), and return value. No contradictions with annotations (readOnlyHint=false, idempotentHint=true, etc.) are present.

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 appropriately dense for the tool's complexity. It is front-loaded with the core purpose and return value, then systematically covers types and delivery options. Some redundancy exists between the description and the schema (e.g., type enum examples), but it remains well-organized and earns its length.

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

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

The description covers all necessary aspects: what the tool does, supported types with parameter syntax, delivery channels with constraints, authentication requirements, return value, and caveats (SMS cap, webhook auto-disable). Given no output schema, mentioning the return value is critical and handled. This is complete 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?

Even though schema coverage is 100%, the description adds extensive meaning: it explains each subscription type's parameter format with concrete examples, clarifies required fields (e.g., 'sponsor or condition required' for clinical_trial), and elaborates on delivery channel semantics (SMS must match verified phone, webhook signing secret). This goes far beyond the schema's descriptions.

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

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

The description states a clear verb ('Create') and resource ('proactive monitoring subscription to a live-data event stream'), and explicitly mentions the return value ('Returns the new subscription id'). It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation and proactive monitoring.

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 for use (proactive monitoring, persistent feed) and mentions requirements (OAuth account, verified phone for SMS). It contrasts with pull-based recent_alerts by noting that the feed is always on and can be pulled via recent_alerts. However, it does not explicitly name alternatives or state exclusions, so a small gap remains.

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?

Even though annotations already declare readOnly/hints, the description adds valuable context: results are 'drawn from the live catalog of thousands of tools' and include 'the exact tool + argument shape.' This reveals the dynamic output structure and source, going beyond the annotations.

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

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

The description is long but every sentence earns its place—it lists example user queries, explains the output, names categories, and gives call variants. It is well-structured and front-loaded with the user's perspective, making it easy to scan.

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

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

With a single optional parameter and no output schema, the description fully covers behavior: what it returns, when to use it, how to focus, and which meta-tools to learn. It is complete for an onboarding 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?

The schema already documents `topic` with the full list of valid areas and the omit behavior (100% coverage). The description merely repeats the same examples ('finance', 'pharma', 'betting') without adding new meaning, so it stays at the baseline 3.

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

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

The description clearly states it is 'the onboarding entry point for an agent that just connected and wants to know what is worth asking.' It specifies the exact output (category-bucketed example questions with tool + argument shape) and differentiates itself from siblings like discover_tools by positioning itself as the FIRST tool to use.

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

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

It explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the two calling modes (no args vs topic) and references sibling tools, providing clear when-to-use and how-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 declare the tool as read-only, non-destructive, and idempotent, covering the safety profile. The description adds a distinct behavioral quirk (one member always dissents) and a process detail (democracy), which goes beyond the structured hints and gives the agent a sense of the tool's inner workings.

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 short sentences, no wasted words. The first sentence identifies the core action, and the following two add relevant behavioral color. It is front-loaded and appropriately sized for the tool's simplicity.

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

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

Given the tool's low complexity, strong annotations, and existing output schema, the description is adequate. It captures the playful yet functional nature of the committee. The only gap is the lack of explicit usage guidance, but that's already reflected in the usage dimension.

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

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

Schema description coverage is 100%, with both optional parameters (urgency, question) clearly described. The description adds no additional parameter context beyond what the schema provides, so it meets the baseline but doesn't enhance understanding of how parameters influence behavior.

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

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

The description clearly identifies a resource (five random number generators) and action (convenes), and the democratic process sets it apart from typical sibling tools. However, it doesn't explicitly state what the tool returns (e.g., a number or decision), so it's slightly less than fully clear.

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

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

No guidance is given on when to use this tool versus alternatives. It doesn't mention use cases like random decision-making or entertainment, nor does it reference any sibling tools or exclusion criteria. The optional 'question' parameter implies a purpose, but the description doesn't articulate 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 adds ownership enforcement and the soft-delete behavior (deactivated, not deleted) beyond the annotations' readOnly/idempotent hints. It also ties the historical events to recent_alerts, disclosing downstream availability. This enriches the agent's understanding of side effects without contradicting annotations.

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

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

Two sentences, with the primary action in the first sentence and necessary context in the second. No wasted words; the ownership and deactivation details are compactly delivered. This is exemplary conciseness.

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

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

For a single-parameter write tool with no output schema, the description covers the cancellation action, ownership constraints, and post-operation state (historical events preserved). It mentions recent_alerts for follow-up, making the tool's impact fully understandable. No additional context seems necessary.

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 provides 100% coverage for the single 'id' parameter, stating it is a uuid returned by subscribe. The description reinforces 'by id' but adds no new format or constraint details. Thus, the schema carries the semantic load, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Cancel') and resource ('subscription by id'), which clearly identifies the action. It also distinguishes this from sibling tools like 'subscribe' and 'list_subscriptions' by explaining the deactivation behavior. This is a precise, non-tautological purpose statement.

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 context that ownership is enforced (only cancel your own subscriptions) and that deactivated rows keep history available via 'recent_alerts', which implies an alternative for viewing historical events. However, it does not explicitly state when to use this versus other tools or provide exclusions like 'do not use if the subscription belongs to another user' directly. The ownership constraint is implicit guidance.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so safety is covered. The description adds high-value behavioral context beyond that: it enumerates the six possible verdicts, explains that 'could_not_verify' means a failed check (not evidence against the claim) and carries a structured error, and clarifies that 'unsupported' means no source was found. This prevents dangerous misinterpretation of results and discloses the two-path routing behavior.

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

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

The description is longer than the minimal example but every section earns its place: trigger phrases, purpose, routing logic, return values, and a critical caller warning. It is front-loaded with the most important info (what it does) and structured with a clear 'IMPORTANT' callout. Minor redundancy exists between 'natural-language claim verification' and the subsequent 'Use whenever' sentence, but overall it is tightly written for the complexity.

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

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

Given no output schema, the description does an excellent job covering return values (verdict enum, actual value, citation, reasoning), error semantics (could_not_verify vs unsupported), routing logic (company-financial vs other), and efficiency (replaces 4–6 calls). It provides enough operational context for an agent to use the tool correctly and interpret results accurately, even without seeing the output schema.

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

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

Schema coverage is 100% and both parameters (claim, tolerance_pct) already have rich descriptions with examples and constraints. The description adds only marginal value about parameters itself (e.g., 'exact percent-delta math'), while the schema fully documents the meaning and default behavior. Baseline of 3 is appropriate since the description doesn't need to compensate for schema gaps.

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 clear natural-language triggers ('Is it true that…', 'fact check', 'verify the claim that…') and immediately states a specific verb+resource: natural-language claim verification against authoritative sources. It also distinguishes itself from sibling tools by explicitly framing the task as claim verification (not general Q&A) and noting it replaces 4–6 sequential calls, showing it is the dedicated fact-checking tool.

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

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

The description gives an explicit 'Use whenever the agent needs to check whether something a user said is factually correct' and explains how different claim types route (SEC EDGAR path vs. grounded pipeline). It does not explicitly name alternative tools or state when NOT to use it, but the built-in routing and claim-specific context make the intended usage clear relative to siblings like ask_pipeworx.

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