Property Records

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

Adds operational details beyond annotations: default model (Workers AI Llama-3.3-70b), cost implications (BYO key, direct payment to Anthropic), and return format. Annotations already cover read-only/idempotent safety, and the description enriches with auth and payment 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?

Four sentences, each earning its place: purpose, default/cost, return format, use cases. Front-loaded with core function and no filler.

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

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

Despite no output schema, description clearly specifies per-model result fields and combined view. Combined with rich annotations and 100% schema coverage, it is complete for a read-only tool.

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

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

Schema coverage is 100% and already describes default model, key requirements, and supported values. Main description adds minimal new info (exact model name), so baseline 3 is appropriate.

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

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

Description clearly states it probes one or more LLMs and scores visibility (0-100) per model, with specific verb ('probe'), resource (LLMs), and output. It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on score-based visibility across multiple models.

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

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

Provides clear use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and cost guidance (free default vs BYO Anthropic key). Does not explicitly mention when not to use or name alternatives, but context is strong.

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

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

Annotations already mark it read-only, idempotent, and open-world; the description adds valuable behavioral details: it routes to 5,529 tools, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and performs one fast call. This goes beyond the annotations and sets accurate expectations for output and performance.

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

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

The description is longer than average but well-structured and front-loaded with the core 'PREFER OVER WEB SEARCH' directive. It includes examples and escalation paths, though some redundancy exists (e.g., 'START HERE' repeats the default emphasis). Every section earns its place for a default entry-point tool.

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

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

For a tool with no output schema and high complexity (universal question answering), the description provides comprehensive context: domain list, example queries, behavioral expectations, comparison to siblings, and handling of breaking news. It fully equips an agent to invoke the tool correctly and interpret its role within the toolset.

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

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

The input schema covers all six parameters with clear alias descriptions and 100% coverage. The description does not add extra parameter-level meaning beyond implying the single argument is a natural-language question. Baseline of 3 is appropriate since the schema carries the burden.

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

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

The description opens with a strong directive ('PREFER OVER WEB SEARCH') and enumerates precise use cases (SEC filings, FDA data, economic stats, etc.). It clearly differentiates from siblings like ask_pipeworx_grounded and deep_research, establishing its role as the default factual question-answer router.

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

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

Explicit guidance states 'START HERE for most questions' and names when to escalate to ask_pipeworx_grounded or deep_research. It also clarifies that breaking-news queries are handled internally, preventing unnecessary use of alternatives. This leaves no ambiguity about tool selection.

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

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

Discloses that it is experimental, may have live candidate routing improvements, and that results are compared against the stable router. Also clarifies 'Falls back to nothing — this IS a full working router', which reassures agents that it is not a fallback. This goes beyond the annotations (readOnly/openWorld/idempotent) by providing context about its beta status and dynamic nature.

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 the key identity ('Beta version of ask_pipeworx') and packs essential information into a few sentences. Each sentence adds value (identity, current state, usage instruction, full-router clarification), but the parenthetical detail about retirement date could be omitted without losing core utility.

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 gives a complete picture for a beta router: what it is, how it relates to the stable version, when to use it, and what to expect (same tools, arguments, response shape). It lacks explicit return-value details but references the stable router's shape, which suffices given no output schema is provided.

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

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

Schema description coverage is 100% and all six parameters are aliases for the same 'question' input, all documented in the schema. The description adds no new parameter-level detail, so the baseline of 3 is appropriate; the schema already handles parameter semantics fully.

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 this as 'Beta version of ask_pipeworx', a universal router with identical behavior to ask_pipeworx but with candidate routing improvements. It distinguishes from the stable ask_pipeworx sibling by explicitly naming it and stating the experimental nature, while also clarifying it is a full working router.

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

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

Explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and explains the comparison process for deciding merges. It also notes when no candidate is active, making the current behavior identical to the stable router, which tells an agent exactly when to choose this tool over alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds substantial behavioral context: it details the internal process (routing, fetching, extracting), specifies the exact success/refusal return shapes, lists refusal reasons, and discloses the extra LLM call cost. No contradiction with annotations.

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

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

While longer than typical, every sentence delivers essential information: the core value proposition, routing behavior, structured return format, refusal conditions, use cases, and cost trade-off. It is front-loaded with the key differentiator ('Hallucination-resistant') and uses structured, scannable syntax.

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

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

Given no output schema, the description fully explains the return structure and refusal reasons. It covers when to use (high-stakes, cited answers), when not to (casual lookups), cost implications, and alternative tools. The annotation set is comprehensive. The description leaves no critical gap for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% description coverage, with all parameters documented as aliases for 'question'. The description does not add any new parameter-level semantics beyond what the schema already explains. Baseline 3 is appropriate since the schema carries the full burden.

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

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

The description starts with a clear, specific verb phrase: 'Hallucination-resistant answer mode for high-stakes reads.' It explicitly names the sibling 'ask_pipeworx' and differentiates this tool by grounding answers strictly in tool results, making its purpose unmistakable.

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

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

The description provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on' and explicitly contrasts with the alternative: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This tells the agent exactly when to choose this tool over its sibling.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, etc.) by detailing internal behavior: parallel fan-out, resolver contract (market_match_confidence, alternatives, suggestions), parent_event extraction, news fallback (_fallback_attempted, _fallback_failed_reason, retry_after_sec), safety short-circuiting (low_confidence_match, market_closed_or_inactive), wide-spread illiquidity handling, and cancellation-rule parsing. It even quantifies the flat-50¢ void settlement risk. This is substantial behavioral disclosure.

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 labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and a front-loaded purpose statement. Every section provides actionable detail, but the length is substantial and some information (e.g., the detailed fan-out examples) could be trimmed without losing core guidance. It earns a 4, not a 5, due to the 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 complexity (no output schema, many behaviors), the description is remarkably complete. It covers input formats, fan-out logic, output structure (result.market, result.analysis, result.evidence), safety statuses, resolver confidence, parent-event extraction, news fallback, and cancellation-rule risk. It even explains edge cases like closed markets and wide spread. Nothing critical seems 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 input schema already provides full descriptions for all three parameters (100% coverage), so baseline is 3. The description adds value by giving concrete examples for 'market' (slug, URL, question text) and explaining the size implications of 'include_raw' (keeps responses under ~20KB vs 50KB-500KB), which helps agents decide when to set it. These additions go 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 and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states what the tool does, and the 'Use for' clause ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') distinguishes it from generic query tools like ask_pipeworx. The classifiers and fan-out examples further clarify the tool's scope.

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

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

The description explicitly says 'Use for' with concrete query types, giving clear when-to-use guidance. It also provides fan-out examples and warns about resolution-rule risks ('Check this before sizing sports/esports/event-occurrence bets'). However, it does not name alternative sibling tools or explicitly state when NOT to use this tool, so it stops short of full exclusions.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description reveals rich behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting behavior by primary metric, and output structure (paired data + citation URIs). This far exceeds what annotations alone convey.

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 carries weight: trigger phrases, core function, usage preference, data source details, sorting, and output. It front-loads the most actionable information and avoids fluff, making it highly efficient despite 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?

For a tool with only two parameters and no output schema, the description is exceptionally complete. It covers context, input semantics, behavior, edge cases (off-calendar fiscal years), and output format, leaving no critical gaps for an agent to infer.

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

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

Although schema coverage is 100%, the description adds significant meaning by enumerating exactly what data each type pulls (e.g., 10-K revenue/net income/cash/debt for companies, adverse-event/approval/trial counts for drugs). It also clarifies value formats (tickers/CIKs vs. drug names), enhancing the schema's basic 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 clearly defines the tool as a side-by-side comparison of 2-5 companies or drugs in one parallel call, with explicit trigger phrases ("X vs Y", "which is bigger") and resource types. It also distinguishes from alternatives by stating it replaces 8-15 sequential single-pack lookups, making its scope 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?

It explicitly instructs "ALWAYS PREFER over sequential single-pack lookups when comparing entities," providing clear when-to-use guidance. It also differentiates company vs. drug scenarios and notes sorting by primary metric, giving the agent concrete 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?

Annotations already declare readOnly/openWorld/idempotent, but the description adds substantial behavioral context: the parallel decomposition into facets, the findings packet structure with gaps[] and contradictions[], the guarantee of never inventing answers, citation_uri fetchability, semantic excerpting, latency expectations, and account/depth-tier constraints. This goes far beyond the annotation hints and provides critical runtime expectations.

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

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

The description is long but densely informative. It front-loads the account prerequisite and alternative tool guidance, then explains core mechanics and depth behaviors, and ends with performance expectations. Every sentence contributes value; however, some clauses could be trimmed (e.g., the list of source types) to reduce cognitive load while retaining key differentiators.

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 and the absence of an output schema, the description is remarkably complete. It specifies return format (findings packet with evidence/confidence/source/fetched_at/citation), the gaps[] behavior, contradictions[] for standard/thorough, citation_uri resolution, large-record excerpting, and explicit timing. It also covers account tiers and alternative tools, leaving no major operational gaps.

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

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

Schema coverage is 100% with the question and depth parameters already described. The description adds value beyond the schema by explaining depth tiers' actual behavior (quick=3 facets, standard adds gap-recovery+contradictions, thorough adds iterative hop and is paid), plus expected latency. The question parameter's schema description already covers natural-language broad questions, so the tool description doesn't need to repeat that. Slight deduction for partial overlap with schema text.

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 a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call. It explicitly differentiates from siblings by stating 'this is NOT open-web search' and contrasts with ask_pipeworx for single lookups, making the tool's role unambiguous.

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

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

Usage guidance is explicit and actionable: 'Best for broad/multi-part questions over structured data' with examples, 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also warns about account requirements and directs unsigned-in users to ask_pipeworx. This fully clarifies when to use this tool vs alternatives.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description doesn't need to repeat that. It adds value by detailing return behavior: top-N tools with full input schemas and curated examples, and that results are directly callable without a second lookup. 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?

Three sentences, front-loaded with purpose. The first sentence defines the tool, the second gives usage and domains, the third explains output and strategic use. No filler, each sentence earns its place. The domain list is long but valuable.

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 meta-tool with no output schema, the description covers all key aspects: what it does, when to use, what it returns, and how results are structured (with schemas). It even gives placement guidance ('Call this FIRST'). Missing minor details like limit defaults, but schema covers that. Complete for its complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level detail; it only says 'describing the data or task,' which aligns with the query parameter but is already covered by schema descriptions. The mention of 'top-N' relates to limit, but again schema covers it.

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+resource: 'Find tools by describing the data or task.' It clearly distinguishes itself as a meta-tool from siblings (which perform specific analyses) by stating it returns tool suggestions with schemas. The listed domain coverage adds concreteness.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' This gives clear context, though it does not explicitly state when NOT to use it (e.g., if you already know the exact tool). The 'not just one answer' hint implies alternatives but doesn't name them.

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

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds significant behavioral context: fan-out across sources, patent soft-fail due to API sunset, news fallback from GDELT→GNews, and return structure details. No contradiction with annotations.

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

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

The description is dense but every sentence adds value. Front-loaded with examples and high-level purpose. It could be restructured into bullets for readability, but it is not wasteful or redundant.

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

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

For a tool with no output schema and high complexity (multiple sub-sources), the description thoroughly explains all returned components (cik, filings, fundamentals, patents, news, LEI), including fallbacks and limitations. Enough for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100% and the description's parameter notes ('Pass ticker AAPL or zero-padded CIK', 'names not supported') are already present in the schema's property descriptions. The description adds examples but no new semantic meaning beyond the structured schema.

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

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

The description explicitly states it creates a 'full cross-source profile of a US public company in ONE parallel call', with concrete user-phrase examples. It distinguishes itself from siblings by naming alternative approaches (chaining lookups, resolve_entity) and specifying scope (US public company, ticker/CIK).

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?

Clear guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and explicit exclusion of names with direction to use resolve_entity first. This gives unambiguous when-to-use/when-not-to-use context.

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

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

Annotations already disclose destructiveHint=true and idempotentHint=true. The description adds specificity about what is destroyed (a memory identified by key) and a rationale (clearing sensitive data). It does not discuss behavior for non-existent keys, but annotations cover the main risk profile.

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

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

Two concise sentences: the first states the core action, the second provides usage guidance and sibling context. Every sentence earns its place with no redundancy.

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

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

For a single-parameter destructive tool with strong annotations, the description fully covers purpose, usage timing, and relationship to related tools. No output schema exists so no return-value explanation is expected. The description is complete.

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

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

Schema coverage is 100% with the property description "Memory key to delete" fully explaining the key. The tool description repeats "by key" but does not add new semantic information beyond the schema, so baseline 3 is appropriate.

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

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

The description opens with a specific verb and object: "Delete a previously stored memory by key." This clearly distinguishes it from the sibling tools remember (store) and recall (retrieve).

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

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

Explicitly provides when-to-use scenarios: "Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier." Also directly names related tools to pair with, giving clear contextual guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond this: it fetches the page, extracts key metadata, and outputs a text blob. This provides insight into the tool's operation and return format, which is not covered by 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 brief and front-loaded, with the main action in the first sentence, followed by process details, output format, and use cases. Every sentence earns its place, and there is no redundant or filler content.

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 simple schema (2 params, no output schema) and rich annotations, the description fills all necessary gaps: it explains the process, the output format, and concrete use cases. The tool's behavior is fully understandable without needing additional information.

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 descriptions cover both parameters (url and max_links) with 100% coverage. The tool description adds no additional parameter-specific meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the specific action: 'Generate a production-ready llms.txt file for any URL'. It also specifies the output format and distinguishes itself from sibling tools by focusing solely on llms.txt generation, 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 provides explicit 'Useful for:' scenarios (client indexing, own project drafting, competitor auditing), which clarifies when to use the tool. However, it does not mention alternatives or when not to use it, so it lacks full exclusion guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable context by enumerating the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying the default behavior of listing only active subscriptions. This goes beyond the annotations.

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

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

Two concise sentences: the first states purpose and return fields, the second gives actionable usage guidance. No unnecessary words or redundancy.

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

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

The tool is simple with one optional parameter and no output schema. The description lists all return fields, explains default filtering, and provides use cases, making it fully self-sufficient.

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

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

Schema description coverage is 100%, so the include_inactive parameter is fully documented in the schema. The description's mention of 'active subscriptions' aligns with the default but does not add additional semantics beyond what the schema provides.

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

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

The description uses a specific verb ('List') and resource ('the caller's active subscriptions'), clearly stating what the tool does. It also distinguishes from siblings by mentioning its use for reviewing before subscribing and finding an id to cancel.

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 context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This names the practical use cases and implicitly references sibling tools (subscribe/unsubscribe), though it does not state explicit exclusions.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false. The description adds substantial behavioral context: the claim_token workflow ('Filing without an account returns a `claim_token`; pass it back later...'), rate limiting ('Rate-limited to 5 per identifier per day'), and cost ('Free; doesn't count against your tool-call quota'). It also explains how feedback is processed ('read digests daily'), which is not in annotations.

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

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

The description is relatively long but every sentence earns its place: purpose, usage criteria, exclusions, claim_token flow, rate limit, and cost. It is front-loaded with the main action and structured to answer likely agent questions in order. 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 tool with 4 params (required: 0), a nested context object, and no output schema, the description provides a complete picture: what to report, how to report, what happens with the response (claim_token), how to check resolution, and operational limits (rate limit, quota). It also clarifies scope (only Pipeworx tools) which is critical for agent decision-making.

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

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

Schema description coverage is 100%, so baseline is 3. However, the description adds meaning beyond the schema for the claim_token parameter by explaining the two-step usage flow and its 'no other arguments' constraint. It also reinforces message specificity ('Be specific (which tool, what error, what data was missing)') and contextualizes the context object. This additional workflow detail justifies 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 description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('Tell') and resource ('Pipeworx team'), and enumerates feedback types (bug, feature, praise) that distinguish it from sibling tools like ask_pipeworx or discover_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?

Explicit guidance on when to use is provided: '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 exclusions: 'if the tool came from a different MCP server... file it with that server instead,' plus a hint for identifying Pipeworx tools. This exceeds minimal guidance.

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

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

Annotations already mark readOnly, idempotent, openWorld, and non-destructive. The description adds valuable context by disclosing the data source (CF analytics-engine), no PII, and caching behavior (5min-1h depending on window), which helps the agent understand freshness and privacy implications 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?

Well-structured with a lead sentence, return summary, use cases, and context. Every section adds value with no redundant phrases or unnecessary details.

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

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

For a simple read-only tool with one optional parameter, the description covers input, output, freshness, and privacy. No output schema exists, but the description conveys the essential return types, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, and the window parameter is already described in detail in the schema. The description adds no new parameter-specific meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description opens with a clear statement of what the tool does ('What other AI agents are calling on Pipeworx right now') and explicitly lists returns: 'Returns the top tools, top packs, and total call volume'. The use cases distinguish it from sibling tools like discover_tools by focusing on current popularity rather than general discovery.

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

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

Provides a 'Useful for' list with three specific scenarios, making it clear when to use. However, it doesn't explicitly name alternatives or state when not to use, so it stops short of a full 5.

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

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

The description goes far beyond the readOnlyHint/idempotentHint annotations, revealing specific thresholds (>3pp deviation), filtering logic (Jaccard ≥0.30), placeholder-slug handling, and the fill-check behavior. It even explains the meaning of null arb signals and that a zero realizable edge means the overround is not in the book. This is rich, non-obvious context that directly informs agent decision-making.

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

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

The description is long but highly structured. It begins with the core purpose, then logically moves through mode selection, semantic anchor, partition filter, response format, and fill-check guidance. Every sentence carries operational weight, and the section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) make the content scannable. 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?

With no output schema present, the description compensates by enumerating response fields: opportunities[] with gap_pp, suggested_trade, reasoning; partition_check with sum_yes_prices, gap_from_1, placeholders_filtered; and fill_check with theoretical vs realizable edge. It also covers mode-specific behavior, thresholds, return signals, and safety warnings, making it fully adequate for complex arbitrage scanning without requiring external lookups.

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 the schema already describes `event` and `topic`, the description adds significant meaning beyond the schema's short definitions. It details what happens in each mode: event walks child markets and checks date-axis/threshold-axis ordering; topic flattens related events and runs comparator on the union. It also provides concrete example slugs and seed questions, substantially enriching the semantic understanding of each parameter.

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, action-oriented statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It then clearly enumerates three invocation modes (no-arg trending scan, event, topic), which distinguishes it from sibling tools like polymarket_edges and polymarket_fill_risk. The purpose is concrete and 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?

Explicit usage direction is provided for each mode: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', and 'pass topic for a themed cross-event scan.' It also gives alternative guidance with 'For custom sizing use polymarket_fill_risk' and warns against trading when realizable_edge_pp ≤ 0. These are clear when-to-use and when-not-to-use signals.

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

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

The description goes far beyond the annotations, detailing internal model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), response segments, diagnostics, and the 1-hour cache keyed on knobs. It also discloses limitations (e.g., 'Fed signal is unreliable without paid data') and includes warnings like the 24h-move note. This is exemplary behavioral transparency.

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

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

The description is dense but well-structured, with clear section headers and bold labels. It front-loads the purpose in the first sentence and then systematically covers model families, response structure, knobs, diagnostics, and caching. While long, every section adds value for a complex tool, so it earns a high score.

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 the response top-level (by_segment, fed_candidates, _diagnostics), including what each segment contains and how to interpret empty results. It also covers caching and edge-case behaviors, making it a complete guide for an agent.

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

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

The input schema already provides comprehensive descriptions for all 9 parameters (100% coverage). The tool-level description adds design rationale for the knobs, especially min_partition_leg_kelly, explaining why 'Partition arbs always return kelly_fraction_half=0 at the parent level by design' — a nuance not in the schema. Thus it adds meaningful context beyond the schema.

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

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

The description opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the intended use case ('what should I bet on today') and distinguishes itself from siblings by focusing on Pipeworx data vs. market price, rather than arbitrage or cross-platform spreads.

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

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

The description provides clear usage context: 'agents discover opportunities without paging hundreds of markets' and explicitly notes that Fed bets are excluded from ranking due to unreliable signal. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of the highest guidance standard.

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 readOnlyHint=true and idempotentHint=true, the description goes far beyond annotations by detailing the response structure (tracked, expired, snapshot_dates), the meaning of trend and decay metrics, snapshot gap behavior, TTL limits, and that decay is computed from daily closes, not intraday. This is rich behavioral disclosure with no contradictions.

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

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

The description is long but exceptionally well-structured with ARGS, RESPONSE, and LIMITS sections. It is front-loaded with the core question ('how long has this edge existed and is it shrinking?') and every sentence carries useful information, making the length justified by 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?

The tool has no output schema, so the description must explain return values, and it does thoroughly: tracked[], expired[], snapshot_dates[] with their semantics, calculation methods, and data limitations. Combined with annotations, this fully equips an agent to understand what to expect and how to interpret results.

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

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

Schema description coverage is 100% for both parameters, so the baseline is 3. The description repeats the defaults and window family options but adds limited new meaning—only linking days to the time-series length and window to the snapshot family. It does not significantly enhance beyond what the schema already provides.

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

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

The description clearly states the tool's purpose as 'edge persistence and decay telemetry' built from daily polymarket_edges snapshots, answering 'how long has this edge existed and is it shrinking?' It identifies the resource (edge snapshots) with a specific verb ('tracks'/'answers') and implicitly distinguishes from sibling polymarket_edges by focusing on time-series persistence rather than current edge data.

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

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

The description provides clear context for when to use this tool: evaluating whether an edge is fresh or old, with the strong hint that 'a fresh wide edge and a 3-week-old wide edge are different trades.' It does not explicitly name alternatives or exclusions, but the scenario is clearly communicated, and the LIMITS section adds practical context about data availability.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and the description adds rich behavioral detail: it 'walks the ladder', returns specific fields, explains partial fill risk, and names 'forced_directional_risk'. It does not contradict annotations and goes well beyond them, describing outputs and failure modes (verdict clean|degraded|cannot_fill).

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 structurally organized with clear labels (SINGLE-MARKET, BASKET, USE THIS) and front-loaded with the core purpose. Every sentence carries information about modes, outputs, or usage guidance; no redundancy or filler.

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

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

With no output schema, the description takes on full responsibility for explaining returns. It lists all return fields for each mode, covers parameter defaults and constraints, provides usage guidance, and addresses risk scenarios (partial fills, thin legs). It is fully 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?

Schema coverage is 100% with per-parameter descriptions, but the tool description adds substantial semantics: mode-dependent meaning of size_usd (max spend vs target proceeds vs settlement notional), side options enumerated per mode, and clarification that exactly one of market or event is required. This goes beyond the baseline schema descriptions and enriches 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 opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk and realizable vs theoretical outcomes. It also clearly delineates two modes (single-market and basket) with distinct purposes.

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

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

Explicitly instructs when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (theoretical overround on thin books is not capturable, partial basket fills convert arb into unhedged directional position), providing clear context and exclusions.

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

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

The description richly discloses behavior beyond annotations: it explains both modes, the response structure (leg-by-leg prices, spread fields), and important safety caveats like compatibility_warning conditions, temporal_alignment, and skipped_cross_type/subtype counters. This adds substantial context on when results are meaningful, which annotations (readOnly/openWorld) do not convey.

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

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

The description is dense and long, but all sentences contribute meaningful operational details (modes, response fields, safety warnings). It is not a model of brevity, yet the structure flows from purpose to modes to response to warnings, making it reasonably scannable for a complex tool.

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

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

Given the tool's high complexity (two venues, multiple matching modes, compatibility risks) and lack of an output schema, the description is unusually complete. It explains what the response contains, when spreads are valid, and how to interpret compatibility warnings and temporal alignment. This covers all major aspects an agent would need to use the tool correctly.

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

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

Schema coverage is 100% with descriptions for each property, so the baseline is 3. The description adds value by clearly explaining the two usage modes and how explicit tickers override topic mappings, which reinforces parameter relationships. It does not fully detail every parameter behavior (e.g., exact format constraints), but it compensates adequately.

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's function: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage by focusing on venue spread with compatibility checks, and explicitly describes two operational modes (topic vs explicit tickers) plus response contents.

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 strong usage guidance: lists pre-mapped topics, explains custom pairing with explicit tickers, and warns that pre-mapped topics are not necessarily tradeable. However, it does not explicitly name alternative tools or state when not to use this tool in favor of a sibling, so it falls short of full explicit exclusions.

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

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

The description goes well beyond the annotations (readOnly, openWorld, idempotent) by detailing what information is returned (market matrix, sales history price inclusion, owner name, assessed value, physical characteristics) and adding caveats about data vintage, refresh cadence, per-jurisdiction nuances, and source URLs. The example also clarifies default behavior with empty input.

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

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

Although the description is relatively long, every sentence earns its place: it defines the tool, lists content, gives usage timing, explains the domain constraint, and provides a concrete example. The information is front-loaded with 'capability matrix for property_lookup' and flows logically to the usage guidance and example.

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

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

Despite having no output schema, the description fully explains what the tool returns (jurisdiction list, field-level availability, vintage, cadence, caveats, source URL). It also covers the important domain context and when to use it. The single optional parameter is simple, and the example clarifies the no-argument case, making the description complete enough for an agent to invoke correctly.

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

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

The schema already fully documents the optional jurisdiction parameter with allowed values (dc | nyc | philadelphia | cook | sf), so schema coverage is high. The description adds value by showing the default behavior via 'Example: {} → 5 jurisdictions' and explaining that the result lists all supported jurisdictions when no parameter is given.

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 this tool as the 'capability matrix for property_lookup' and enumerates exactly what it contains: county/city coverage, per-field availability, data vintage, refresh cadence, caveats, and source URL. This specific verb+resource pairing and scope make it distinct from sibling property_lookup and other 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?

It provides explicit guidance: 'Use this before promising a user an answer' to verify county and field availability. It also gives context about US property records being county-maintained and no national source, implying this tool is the prerequisite coverage check before performing an actual lookup via property_lookup.

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

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

Annotations already declare read-only/idempotent, so the description adds valuable context: keyless access, jurisdiction scope, covered:false responses for unsupported counties, data variations (SF no price), and dependence on county publication. 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 front-loaded with the core purpose and well-structured with examples and jurisdiction list. Every sentence contributes useful information, though 'keyless public records, no API key' is slightly redundant.

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

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

With no output schema, the description compensates thoroughly: it states return fields, demonstrates via concrete examples, explains unsupported-jurisdiction behavior, and notes per-jurisdiction data limitations. This gives an agent full context for selecting and invoking the tool.

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

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

Schema coverage is 100%, but the description adds meaning by explaining address as free text with flexible formatting and optional city/state/ZIP improving inference, and it lists valid jurisdiction values in prose. This exceeds the baseline schema-only understanding.

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

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

The description clearly states it retrieves address-level US property records from county/city open-data portals, lists specific questions it answers, and explicitly distinguishes itself from the property_coverage sibling by directing callers to that tool for a capability matrix.

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 names property_coverage as an alternative for capability-matrix queries and clearly explains supported jurisdictions plus the behavior for unsupported addresses (covered:false). It doesn't explicitly say 'use when not appropriate,' but the jurisdiction limitation and covered:false response make the usage context unmistakable.

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 that results are 'scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and that omitting the key lists all saved keys—behavioral details not present in the annotations.

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

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

Three sentences accomplish action, usage scenario, and scoping. No redundant wording; each sentence earns its place.

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

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

For a one-parameter read-only tool with no output schema, the description covers behavior, scoping, listing behavior, and related tools. An agent has enough context to invoke it correctly.

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

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

The schema describes the key parameter fully (100% coverage), but the description adds meaningful semantics: omitting the key lists all keys, and the examples (user's target ticker, address, research notes) clarify what kind of values are stored.

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+resource structure: 'Retrieve a value previously saved via remember, or list all saved keys.' This clearly states the tool's function and distinguishes it from the sibling tools remember (save) and forget (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?

It explicitly tells the agent when to use it: 'Use to look up context the agent stored earlier' and contrasts with re-deriving information, plus points to remember and forget as paired tools, covering the usage cycle.

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 annotation declares readOnlyHint=true, but the description discloses that setting mark_read=true flags events as read, which is a state-modifying side effect. This contradicts the read-only annotation, and per rubric, transparency must be scored 1 when a contradiction exists.

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 4 sentences, front-loaded with the main purpose, and includes only relevant details: filtering, mark_read, polling, and an alternative access method. No wasted words.

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

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

Without an output schema, the description compensates by specifying the return payload (source, citation_uri, raw event). It covers filtering, mark_read persistence, and the polling/endpoint alternative. Minor gaps like the interaction between mark_read and unread_only remain, but overall it is thorough.

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 5 parameters, but the description adds valuable context beyond schema: it explains the mark_read behavior in detail (affects future calls), provides an example filter value (sec_8k), and describes the response structure, enhancing understanding.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifying the action and resource. It details the content of returned events (source, citation_uri, payload) and provides filtering examples, making its purpose distinct from siblings like 'recent_changes'.

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 notes that polling works fine and points to an alternative endpoint for scripts/dashboards, giving clear usage context. It doesn't list when to avoid this tool vs. siblings, but the guidance is sufficient for typical use.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: it explains the fan-out to SEC EDGAR, GDELT→GNews fallback (GDELT preferred, GNews on rate-limit/5xx), and the USPTO PatentsView API sunset soft-fail. It also discloses the return structure (changes[], total_changes, citation URIs), which goes well 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 longer than the minimal example but each sentence serves a distinct purpose: intent examples, core definition, source fan-out details, `since` format, return shape, and alternative tool. It is front-loaded with the core purpose and organized logically, though the density makes it slightly less immediate than a two-sentence description.

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 sufficiently explains return values (structured changes[], total_changes, citation URIs). It covers operational caveats like GDELT→GNews fallback and the PatentsView sunset soft-fail, and provides the alternative tool for static needs. For a multi-source aggregation tool, this is complete and 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?

Schema description coverage is 100%, so the baseline is 3. The description adds extra semantics for `since` (relative shorthand examples like '7d', '30d', '3m', '1y', and typical usage guidance) and clarifies `value` as ticker or zero-padded CIK, reinforcing the schema. However, the schema already describes each parameter meaningfully, so the description provides marginal but useful enhancement.

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 a change feed for a company, starting with real-world example queries ('What's new with X', 'latest on Y') and then defining it as 'change feed for a company in the last N days/weeks/months in ONE parallel call'. It also distinguishes from the sibling tool entity_profile by explicitly stating when to use that instead, satisfying the sibling differentiation criterion.

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: it names the alternative tool (`entity_profile`) for static profiles, specifies the temporal scope ('in the last N days/weeks/months'), and details the `since` parameter formats with a typical recommendation ('Use "30d" or "1m" for typical monitoring'). This constitutes explicit when-to-use and when-not-to-use guidance beyond generic context.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds valuable context beyond that: key-value scoping by identifier, persistence behavior (authenticated vs anonymous 24h retention), and pairing with recall/forget. No contradictions with annotations.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence adds value: purpose, usage, storage behavior, persistence details, and sibling relationships. No fluff or repetition.

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

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

For a simple 2-parameter write tool with no output schema, the description covers purpose, usage, retention, scoping, and related tools. It is complete for an agent to select and use the tool correctly.

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

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

Schema description coverage is 100%, and both parameters are well-documented with examples. The description does not add additional parameter-specific meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description uses a specific verb+resource ('Save data') and clearly distinguishes from sibling tools by naming recall and forget as complementary actions. It also provides concrete examples of use cases (ticker, address, preference) that make the purpose instantly clear.

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

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

The description explicitly states when to use the tool ('Use when you discover something worth carrying forward') and gives examples. It also names alternatives/complements (recall, forget), satisfying the when/alternatives criterion.

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 crucial behaviors: identifiers are labeled with their source, unresolved identifiers are explicitly listed under 'unresolved' rather than omitted, and LEI/FIGI enrichment degrades gracefully when external sources fail. This adds significant context and does not contradict any annotation.

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

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

The description is lengthy but front-loaded with examples and the core purpose. The 'SUPPORTED TYPES' section is dense and could be better structured, but each sentence provides useful information about outputs and fallbacks. It earns a 4 for being informative yet slightly overwrought.

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 ably covers what is returned for each type, including unresolved identifiers, source labels, and graceful degradation. It also explains the cascading internal lookups, making it self-sufficient for an agent to understand the tool's behavior and outputs.

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 provides detailed descriptions for both parameters, including formats and examples. The description largely restates the 'accepts ticker, CIK, or company name' information, adding no new parameter-level semantics beyond what the schema provides.

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

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

The description is exceptionally clear: it opens with concrete example user queries, then states the tool's exact purpose ('resolve a user-spoken NAME to the canonical/official identifiers other tools require as input'). It specifies supported entity types and their outputs, clearly distinguishing it from sibling tools by indicating this is the first step to obtain IDs.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' which is a clear when-to-use signal. It also notes this tool replaces multiple manual lookups, implying efficiency. However, it doesn't explicitly name alternative tools or state when NOT to use it, 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful behavioral details: it probes each entity via ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This gives the agent a clear model of what happens during execution beyond the structured annotations.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence contributes value. It explains what it does, how it works, when to use it, and what it returns without waste.

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 explicitly states the return structure ('ranked list with score, confidence, signal density per entity'). It also covers the tool's internal mechanics, use case, and parameter behavior, making it sufficiently complete for the tool's moderate complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds high-level context (comparing 'your brand + N competitors') but does not provide additional details about parameter formats or edge cases beyond what the schema already explains. It neither improves nor reduces clarity.

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 ('Compare'), names the resource ('AI visibility across multiple entities'), and clearly distinguishes from the sibling ai_visibility_check tool by emphasizing side-by-side comparison of multiple entities and ranking. It also explains the output (ranked list, most/least recognized) which adds purpose clarity.

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

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

The description provides a clear use case ('competitive AI-marketing audits') with an example question, and the context implies when to use it versus a single-entity check. However, it does not explicitly name alternative tools or state when not to use it, so it falls just 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, non-destructive), the description discloses important behavioral traits: it fans out across two external services, partial failures degrade gracefully, and bundlephobia's first measurement can take 5-30s with sources_failed listing timeouts. It also explains what happens on timeout ('the rest still returns'), providing rich context that annotations alone do not. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: purpose, use case, return contents, ecosystem scope, and failure semantics are all covered without redundancy. It is front-loaded with the main composite purpose, and the limitations appear after the core context. No filler or tautological phrases; the length is justified by the tool's complexity.

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

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

Given the composite nature (two external services, partial failures, no output schema), the description fully covers usage, ecosystem constraints, return fields, performance caveats, and failure behavior. It enumerates the summary block fields and mentions per-advisory detail and links. There is no output schema, so the description's rich return-value disclosure is essential and sufficient.

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

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

Schema coverage is 100% for both parameters (package and version), and the schema already describes their types, defaults, and scoped package support. The description adds no new parameter-specific meaning beyond what the schema provides; it only reflects the schema's 'latest published version' default. With high schema coverage, 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 composite purpose: a one-call check for 'should I add this npm package' combining deps.dev and bundlephobia. It specifies the exact resources and data sources, and distinguishes itself by ecosystem scope (NPM only) and differentiation from the direct deps.dev:version fallback. The phrasing 'Composite ... check in ONE call' is a specific verb+resource+scope that fully clarifies what this tool does.

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

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

The description provides explicit usage triggers: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives clear exclusions by stating 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', naming the alternative tool. This gives the agent concrete criteria for when to invoke this tool versus 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 annotations (read-only, idempotent, open-world), the description adds substantial behavioral detail: the embedding model (BGE-base-en), similarity metric (cosine), chunking method (500-char overlapping windows), and hard input cap of 200K chars with truncation flagging. It also promises character offsets for verifiable quoting, giving the agent full transparency about how the tool operates.

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 a crisp purpose statement, followed by a use case, a pairing note, and technical constraints. Every sentence adds distinct value (purpose, when-to-use, verification benefit, implementation details), and no sentence is wasted. The density is justified by 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 format (top-N passages, character offsets, similarity scores) and covers edge cases (200K char cap, truncation flag). It also situates the tool within a workflow (pairs with ask_pipeworx_grounded), making the description complete for operational decision-making.

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

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

The input schema already covers 100% of parameters with clear descriptions: text (document text, max ~200K chars), query (natural-language query with examples), and limit (max passages, default 5). The description adds only minor enrichment (e.g., examples of text types like SEC 10-K), so the schema carries the interpretive burden—hence 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 opens with the specific action and resource: 'Semantic search INSIDE a fetched record.' It goes on to detail the input (text + query) and output (top-N passages with character offsets and similarity scores), and provides concrete examples (SEC 10-K, article) that make the purpose unmistakable and distinct from sibling search/Q&A 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 it: 'Use when the record is too big to cram into the prompt' and explains the complementary workflow with ask_pipeworx_grounded. It does not explicitly state when not to use it (e.g., for small documents), but the guidance is clear enough for a capable agent.

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 substantially augments annotations with critical behavioral details: account persistence requirement, phone verification and 10/day SMS cap, webhook auto-disable after 10 failures, one-time webhook secret issuance, and the always-on feed. These go far beyond the annotations' readOnly/openWorld/idempotent hints, offering rich transparency into side effects and constraints.

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

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

The description is dense and lengthy, but every sentence contributes essential information given the tool's complexity (5 types, 3 delivery channels). It is front-loaded with the main action and return value, and uses structured examples to improve scannability. Slightly overlong but 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?

Given the tool's complexity (nested objects, enums, no output schema), the description is remarkably complete. It covers prerequisites, return value, all subscription types with examples, delivery channel behaviors, and operational limitations. No critical gaps were found.

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 schema coverage is 100%, the description adds meaningful value by explaining type-specific examples (e.g., sec_8k items codes, polymarket_edge topic) and delivery channel requirements such as phone verification and webhook signing. The schema already covers basic param structure, so the description's enhancements earn a 4 rather than 5.

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: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This uses a specific verb (create) and resource (subscription), and distinguishes it from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 clear context including prerequisites ('Requires a Pipeworx OAuth account'), supported subscription types, and delivery channels. However, it does not explicitly mention alternatives like list_subscriptions for viewing existing subscriptions or unsubscribe for removing them, so it lacks explicit exclusions.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral detail: it returns category-bucketed questions, includes tool+argument shape, supports optional topic filtering, and is drawn from a live catalog. No contradiction.

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

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

The description is long but packed with useful information. It is front-loaded with the purpose and return type, and the opening query examples, while somewhat verbose, help identify the tool's entry-point role. The length is justified by 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?

Since there is no output schema, the description fully compensates by explaining the return structure (category-bucketed questions with tool+argument shape) and usage scenarios. It covers purpose, behavior, parameter, and alternatives, making it complete for an agent.

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

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

The input schema already fully describes the `topic` parameter, including the allowed values and the omit behavior. The description merely restates this information, adding no new semantic meaning beyond what the schema provides.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point for an agent that wants to know what to ask Pipeworx. It specifies the output (category-bucketed example questions with exact tool + argument shape) and distinguishes itself from siblings by positioning as a first-stop and mentioning meta-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?

Explicit when-to-use guidance is given: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also names alternatives (meta-tools) and explains how to use the parameter, making the usage context very clear.

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

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

Descriptions adds key behavioral traits: ownership enforcement, soft-delete semantics ('deactivated not deleted'), and the consequence that historical events remain available via recent_alerts. These go beyond the annotations (idempotent, non-destructive, mutating) and give the agent practical knowledge.

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, each carrying distinct information: action, constraint, and consequence. No wasted words.

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

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

For a single-parameter cancellation with no output schema, the description covers action, ownership, side effects, and historical data access. The annotations further cover idempotency and destructiveness, making this fully self-sufficient.

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

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

The schema already describes the id parameter as the subscription uuid returned by subscribe, so coverage is complete. The description's 'by id' is redundant, but no additional parameter information is missing. Baseline score 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 uses a specific verb ('Cancel') and resource ('subscription') with an explicit ID-based operation, clearly distinguishing it from sibling tools like subscribe and list_subscriptions. The scope is unambiguous: cancel a single subscription by id.

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

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

It provides clear context: ownership is enforced (only your own subscriptions), and the effect is deactivation rather than deletion, which points to recent_alerts for historical data. It doesn't explicitly name alternatives, but the 'not deleted' clause implies when this is appropriate versus when a harder delete might be needed.

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

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

Annotations already declare the tool read-only, idempotent, and open-world. Beyond this, the description reveals two internal pipelines (SEC EDGAR/XBRL fast path vs. grounded pipeline), explains the verdict meanings, and adds a critical caveat that could_not_verify indicates a failure and must not be presented as evidence. This significantly exceeds the annotation-only picture and covers 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: trigger phrases, core purpose, routing details, output summary, and cautions. Every sentence earns its place, though it is wordier than strictly necessary. It is front-loaded with purpose and usage, but the length prevents a perfect score.

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 six possible verdicts, the return content (grounded/structured value, citation, reasoning), and the special error object for could_not_verify. It also explains the scope of unsupported and the replacement of a sequential pipeline, making the tool's behavior clear and self-contained.

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

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

Schema coverage is 100%, and both parameters already have thorough descriptions. The main description's reference to 'exact percent-delta math' and implied tolerance adds some context, but it largely echoes the schema and does not introduce new parameter-level meaning. 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 opens with explicit user phrasings and identifies the tool as 'natural-language claim verification against authoritative sources.' It clearly specifies the resource (claims) and the action (verify), enumerates possible verdicts, and differentiates internal routing (financial vs. other claims), making it distinct from generic search or research 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?

Provides an explicit usage directive: 'Use whenever the agent needs to check whether something a user said is factually correct,' with multiple query examples. It also clarifies the distinction between could_not_verify and unsupported, guiding post-invocation behavior. However, it does not name sibling tools or explicitly state when to choose an alternative, 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.