Treasury Fiscal

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

Annotations confirm read-only, idempotent, non-destructive behavior. Description adds critical context: default model is free, Anthropic requires BYO key and direct payment, and it returns per-model scores with raw responses. This goes beyond annotations to clarify cost and output structure.

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

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

Description is three sentences: first states main function, second adds detail on models and cost, third lists output and use cases. Every sentence is valuable, concise, and front-loaded with the core purpose.

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

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

Despite no output schema, the description explains the return format (per-model {score, confidence, signals, raw_response} + combined view). It covers all parameters, use cases, and cost implications. For a 4-parameter tool with no nested objects, this 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 detailed descriptions. Description adds extra context to 'models' (default is workers-ai, Anthropic requires key), '_apiKey' (BYO key, paid directly), and 'context' (disambiguation). This enriches the schema descriptions, warranting above-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?

Description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the default model and the optional Anthropic probe, distinguishing it from sibling tools like 'scan_competitor_ai_presence' which likely focuses on competitors.

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

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

Description explicitly states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the optional API key. However, it does not explicitly state when not to use this tool (e.g., for real-time data or deep analysis), but the examples provide sufficient 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?

Description adds known behavior—routes question to 3,745 tools across 884 sources and returns citation URIs—beyond annotations (readOnly, openWorld, idempotent). No contradictions.

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

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

Front-loaded with key preference statement. Some redundancy in listing use cases, but concise overall for the scope.

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

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

Given no output schema, description adequately covers input flexibility, return type (structured answer with citations), and domain coverage.

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

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

Schema already documents all 6 aliases for the same field. Description adds natural language context and examples but does not add deep semantics 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?

Clearly states it's for answering factual questions using authoritative structured data, preferring over web search. Distinguishes itself from siblings like deep_research by emphasizing breadth of sources.

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

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

Explicitly recommends over web search for many specific data types and provides example queries. Lacks explicit when-not-to-use, but context makes it clear.

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

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

Beyond annotations, describes the extraction process, return shape (answer, evidence, confidence, source, etc.), and explicit refusal reasons (not_in_source, no_tool_match, etc.). Annotations already indicate read-only, but description adds detail on how results are used.

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

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

Front-loaded with purpose and mechanism, then use cases and cost. Every sentence adds value. No fluff.

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

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

Despite no output schema, the description fully details the return object and refusal modes. Covers behavior, use cases, constraints, and cost. Complete for a high-stakes read tool.

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

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

Schema coverage is 100%, with each parameter clearly documented as alias for question. Description does not add further semantics beyond noting it accepts natural language. 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?

Clearly states it is a 'hallucination-resistant answer mode' that 'extracts the answer using ONLY what the tool result contains'. Distinguishes from sibling ask_pipeworx by emphasizing grounded extraction and refusal behavior.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on...' and provides examples (financial verdicts, legal claims). Also states preference for ask_pipeworx for casual lookups due to extra cost.

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 exhaustively discloses behavioral traits beyond annotations: resolver contract (market_match_confidence, alternatives), parent event extractor, news fallback info, safety short-circuits (low_confidence_match, market_closed_or_inactive), illiquid spread handling, and cancellation rule parsing. Annotations (readOnlyHint, idempotentHint) are consistent and the description adds substantial context.

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

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

The description is long (~600 words) but well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads the primary purpose and key use cases. Minor deductions for verbosity, though justified by tool complexity.

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

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

Given the tool's complexity (3 parameters, no output schema), the description comprehensively covers inputs, classifiers, fan-out examples, response shapes, resolver contract, parent event extraction, news handling, safety mechanisms, and cancellation rules. It leaves no significant behavioral gaps for the agent.

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

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

Despite 100% schema description coverage, the description adds significant meaning: it explains how 'market' accepts slugs, URLs, or question text; 'depth' (quick vs thorough) with fan-out implications; 'include_raw' with specific scenarios for using true (recompute deltas, cite observations). This enriches the agent's understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison), distinguishing it from sibling tools like ask_pipeworx or polymarket_edges by focusing on a single bet with data fan-out.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also gives guidance on when not to proceed (low-confidence matches, closed markets) and details blocking conditions, ensuring the agent knows appropriate contexts.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral details: off-calendar fiscal years handled correctly, results sorted by primary metric, returns citation URIs. No contradictions.

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

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

Description is somewhat verbose but well-structured: starts with trigger phrases, then details each type and behavior. Every sentence adds value; front-loads key usage guidance. Slight redundancy could be trimmed.

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 rich schema and annotations, description covers necessary context. No output schema exists, but description mentions return format (paired data + citation URIs). Could mention that results are sorted by primary metric for rank queries.

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

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

Schema coverage is 100%, but description adds significant meaning: explains that type='company' pulls SEC data and type='drug' pulls FAERS data. Clarifies values format (tickers/CIKs or drug names) and constraints (2-5 items).

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 tool does side-by-side comparison of 2-5 companies or drugs, with specific data sources and metrics. Verb 'compare' and resource 'entities' are explicit. Distinguishes from siblings like entity_profile (single entity) by emphasizing parallel lookup.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups' and lists trigger phrases like 'which is bigger' and 'head to head'. Provides context for when to use vs. alternative approaches (single lookups).

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds significant behavioral context: decomposition into sub-questions, parallel routing, evidence with citation, gaps for unanswered facets, pre-verified facts, and expected time (15-60s). No contradictions.

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

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

Description is well-structured with bold summary, process, usage, and requirements. Every sentence adds value, though slightly verbose. Could be more concise while maintaining clarity.

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

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

No output schema, but description fully covers return value (structured findings packet with citations, gaps, source, fetched_at). Also accounts for prerequisites, time expectations, and limitations. Complete for a complex tool.

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

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

Schema coverage is 100% with basic descriptions. Description adds value by specifying numeric meaning for depth enum (quick=3, standard=5, thorough=8) and clarifying that broad/multi-part questions are fine. Enriches beyond baseline 3.

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

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

The description clearly states the tool's purpose: grounded multi-source research in one call. It specifies the verb (decompose, extract) and resource (multi-source research), and distinguishes from sibling ask_pipeworx for single lookups.

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

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

Explicitly provides when to use (broad/multi-part questions) and when not (single lookups, use ask_pipeworx). Also mentions prerequisites (Pipeworx account) and limitations (depth:thorough requires paid plan).

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 it returns top-N relevant tools with schemas and examples, ready to call directly. Annotations confirm read-only, idempotent, non-destructive. 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?

Description is somewhat lengthy with a bullet list of domains, but front-loaded with purpose. Could be trimmed, but provides necessary context without excessive fluff.

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

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

Despite no output schema, description specifies what is returned (names, descriptions, schemas, examples). Annotations cover safety. Sufficient for a discovery 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%. Description adds natural language query examples (e.g., 'analyze housing market trends') that enhance agent understanding beyond schema descriptions.

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

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

Description clearly states it finds tools by describing data or task, lists many example domains, and distinguishes itself as a discovery tool to call first.

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.' Could be more explicit about when not to use, but sufficient.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds significant behavioral details: it fans out across multiple sources, provides fallback mechanisms (GDELT→GNews), notes a soft-fail for USPTO patents due to sunset, and explains the single parallel call 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 appropriately sized for the tool's complexity, front-loaded with example queries, and every sentence adds specific value without redundancy.

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

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

Given the absence of an output schema, the description thoroughly explains the return structure (cik, recent_filings with URIs, fundamentals, patents, news with fallback, LEI) and acknowledges limitations (USPTO sunset, name not supported). No gaps remain for an agent to understand the tool's behavior.

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% with descriptions for both 'type' and 'value', the description adds meaning by explaining the supported value formats (ticker or zero-padded CIK), restating that names are unsupported, and clarifying the 'type' parameter's current limitation to 'company' only.

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

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

The description explicitly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' and lists specific data sources and return fields. It distinguishes itself from sibling tools like 'resolve_entity' by noting that names are not supported.

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 contains an explicit directive to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies when to use an alternative: 'names not supported (use resolve_entity first if you only have a name).'

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

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

Annotations already provide destructiveHint=true and idempotentHint=true, and the description's 'Delete' aligns. However, it adds no further behavioral context (e.g., behavior on missing key, side effects) beyond what annotations already 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?

Two concise sentences with no wasted words; front-loaded with the core action and followed by usage context.

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

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

For a simple tool with one parameter and no output schema, the description covers what, when, and complementary tools completely.

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 the description merely restates 'by key' which is already in the param description. It adds no additional meaning or formatting guidance 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 uses a specific verb ('Delete') and resource ('previously stored memory by key'), clearly distinguishing it from siblings like 'remember' and 'recall' by mentioning pairing.

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

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

It explicitly states when to use the tool (stale context, task done, clear sensitive data) and suggests pairing with remember and recall, but does not mention when not to use it or alternatives beyond the siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by detailing the process ('Fetches page, extracts title/description/key links, emits standard llms.txt format'). No contradictions.

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

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

The description is two sentences plus a usage line, with no wasted words. It front-loads the core action and then provides context, making it efficient and easy to parse.

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 two parameters, full schema coverage, and rich annotations, the description provides adequate context about output (text blob) and use cases. No output schema is needed as the description clarifies the return type.

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

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

Schema coverage is 100%; the description adds no new parameter details beyond the schema. It explains the output format, which mildly compensates, but the schema already covers parameters 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 states the tool's action: 'Generate a production-ready llms.txt file for any URL.' It specifies the target AI crawlers and the output format, distinguishing it from siblings by being unique in purpose.

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

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

The description lists specific use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, auditing a competitor'), providing clear context. It lacks explicit when-not-to-use or alternatives, but the use cases are well-defined.

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

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

Annotations already indicate readOnly and idempotent. Description adds default behavior (lists active subscriptions) and return structure, enhancing 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?

Two sentences front-load essential information: purpose and returns first, usage guidance second. 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?

Covers all aspects: purpose, returns, usage context, default behavior. Without output schema, the return fields are explicitly listed, making it complete for a simple 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%; the only parameter (include_inactive) is fully described in the schema. Description adds no new parameter info, so 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?

Clearly states 'List the caller's active subscriptions' with specific verb and resource. Returns enumerated fields (id, type, etc.) distinguishing it from siblings like subscribe/unsubscribe.

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

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

Provides explicit context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Lacks explicit when-not-to-use but offers clear guidance.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false. The description adds that the tool sends feedback and is rate-limited, but does not delve into side effects or authorization. It aligns with annotations without contradiction.

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

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

The description is well-structured with a clear purpose statement followed by usage conditions and parameter guidance. It is concise for the information provided, though some sentences are longer. Still, every sentence earns its place.

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

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

For a feedback tool with no output schema, the description is complete. It covers purpose, when to use, rate limiting, and parameter semantics. No additional context is needed for proper invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the enum values (bug, feature, etc.) in human terms, and clarifies the message and context fields. It goes beyond the schema to guide proper usage.

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

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

The description clearly states it's for sending feedback (bugs, features, data gaps, praise) to the Pipeworx team, distinguishing it from other tools by focusing on tool-related issues. The verb 'send' and resource 'feedback' are specific and actionable.

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 tells when to use the tool: for bugs (wrong/stale data), features (missing tool), data_gap, or praise. It also mentions rate limits (5 per identifier per day) and that it's free, providing clear context for use-case differentiation.

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, idempotentHint, etc. The description adds value by explaining the data source (CF analytics-engine), lack of PII, caching behavior (5min-1h), and aggregation method. 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 well-structured with a clear opening, bulleted use cases, and a closing behavioral note. Every sentence adds value; no redundancy. It is concise for the amount of information conveyed.

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

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

Given the complexity (read-only analytics, one parameter, no output schema), the description fully covers all necessary context: what is returned, how it's derived, privacy, caching. No gaps.

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

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

Schema coverage is 100%, and the description adds meaning: it explains the trade-off between windows ('shorter windows surface what's hot right now') and caching details per window. This goes beyond the schema's enum list.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a recent window, with a specific verb ('returns') and distinct resource ('what other AI agents are calling on Pipeworx'). It differentiates from siblings like ask_pipeworx, which are for asking questions.

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

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

Three explicit use cases are provided, covering discovery, confirmation, and alignment. The description implies when not to use (if you need to ask a question, use ask_pipeworx) and gives clear context for each use case.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, destructiveHint. Description adds rich behavioral details: monotonicity checks, partition-sum checks, Jaccard similarity threshold, placeholder filter, fill check using CLOB depth with trading guidance. 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?

Well-structured: starts with requirement, then mode descriptions, then technical details. Every sentence adds value, but the description is somewhat lengthy. Could be slightly more concise but justified by the complexity of the tool.

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

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

Describes input, modes, algorithms, output structure (opportunities array, partition_check object), and edge cases (fill check, placeholder filter). Missing explicit handling of no-opportunity case and exact placement of skipped_low_similarity in response. Nearly 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 basic descriptions. Description adds meaning: explains event accepts slug or full URL, topic is seed question for cross-event scanning, and that no-args call fails. Provides examples, exceeding baseline of 3.

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

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

Clear verb+resource: 'Find arbitrage opportunities on Polymarket'. Distinguishes two modes (single-event via event, cross-event via topic). Distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection and explicitly mentioning polymarket_fill_risk for custom sizing.

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

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

Explicitly states requirement of one of event or topic, recommends event for specific market and topic for cross-event scanning. Mentions cross-event mode catches patterns single-event misses. Points to polymarket_fill_risk for custom sizing. Lacks explicit exclusions for all sibling tools but provides adequate 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 indicate read-only, idempotent, and non-destructive behavior. The description adds rich behavioral context: caching at KV level keyed on all knobs, detailed model families, edge calculation, diagnostics for empty segments, and tradeable-edge knobs. 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 front-loaded with the main purpose but becomes verbose with extensive technical details on model families. While well-structured, some sentences could be condensed without losing meaning.

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

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

Given 9 parameters and no output schema, the description is highly complete. It explains output structure (by_segment, fed_candidates, diagnostics), parameter interactions, and caching behavior, and covers all necessary context for an AI agent.

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

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

Schema description coverage is 100%, providing baseline semantic information. The description adds extra context on how parameters like min_liquidity, max_spread_pp, and min_partition_leg_kelly work together, justifying a score above baseline.

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

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

The description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' – a specific verb+resource. It also distinguishes from siblings by explaining the three segments and the 'what should I bet on today' use case.

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

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

The description states the tool is built for discovering betting opportunities and that it saves paging hundreds of markets, providing clear context. However, it does not explicitly mention when not to use it or suggest alternatives like polymarket_arbitrage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral details: data source (daily snapshots), snapshot gaps meaning no scan that day, decay calculation (from daily closes of edge_pp_net, not intraday), and response structure (tracked, expired, snapshot_dates). No contradictions with annotations.

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

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

The description is well-structured and front-loaded with the key question it answers. It covers purpose, response fields, and limitations concisely, though it is slightly verbose. Every sentence adds value, but some details could be condensed.

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

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

Given the complexity of the tool (time-series analysis, trends, decay) and the lack of an output schema, the description thoroughly explains all returned fields (tracked, expired, snapshot_dates) and limitations (TTL, gaps, decay computation). It provides a complete understanding of what the tool returns and its constraints.

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 repeats parameter info (days, window) but adds no new meaning beyond what the schema already provides. It does not clarify syntax or format beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily polymarket_edges snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on the time dimension.

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

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

The description implies when to use the tool (to differentiate fresh vs. stale edges) and provides context (e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades'). It also mentions limitations (60-day TTL, gaps), which guides usage, though it does not explicitly name alternatives or when not to use.

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

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

The description discloses extensive behavioral traits beyond the annotations: the check is against live CLOB order-book depth, and it details return fields (top_of_book, vwap_fill_price, etc.), verdict categories, and risks like forced directional risk. There is no contradiction with the readOnlyHint=true and other annotations.

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

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

The description is well-structured with capitalized mode headers and front-loaded purpose. It is relatively long but every sentence adds value. It could be slightly more concise by moving some defaults into the schema descriptions, but overall it's efficient given the complexity.

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

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

Given the parameter count, lack of output schema, and no nested objects, the description is remarkably complete. It explains both modes, return fields, edge cases, and warnings about partial fills. It covers everything an agent needs 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 already covers all 4 parameters with descriptions. The tool description adds significant context by explaining how parameters differ between single-market and basket modes, default values, and interpretation of size_usd (settlement notional for baskets). This enriches the schema but the schema already provides full coverage.

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

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

The description clearly states the tool's purpose: a realizable-vs-theoretical edge check against live order-book depth. It specifies two distinct modes (single-market and basket) and explicitly distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by advising when to use it before those actions.

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

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

The description provides explicit guidance on when to use this tool: before acting on polymarket_arbitrage signals or trades above ~$500. It explains why it is necessary, citing that theoretical overround on thin books is not capturable and that partial basket fills create directional risk.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description significantly adds behavioral context: details on compatibility_warning, temporal_alignment, skipped metrics, and that pre-mapped topics are not necessarily tradeable. This goes well beyond annotations.

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

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

The description is relatively long but well-structured: it front-loads purpose, then mode details, response fields, and safety warnings. Every sentence adds value, though it could be slightly more concise without losing information.

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

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

With no output schema, the description thoroughly explains the response structure (leg-by-leg prices, matched spreads, safety fields) and parameter semantics. It covers all necessary context for an agent to use the tool correctly, including caveats about when spreads are meaningful.

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 value by enumerating the 10 topic shortcuts and explaining that explicit tickers override topic. This enriches meaning beyond the schema's brief descriptions.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, using a specific verb+resource structure. It distinguishes from sibling tools like polymarket_arbitrage by targeting cross-venue spreads, and from compare_entities by focusing on prediction markets.

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

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

The description provides clear context on when to use: for comparing same outcome across two venues. It explains two modes (topic shortcuts vs explicit tickers) and includes safety fields that indicate when spreads are meaningless. However, it does not explicitly state alternatives or exclusions, e.g., 'use polymarket_arbitrage for intra-venue spreads'.

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 (safe read) and destructiveHint=false. Description adds that it retrieves previously saved data, is scoped to identifier, and pairs with remember/forget. No contradictions.

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

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

Three sentences, front-loaded with the core function. Every sentence adds value: first sentence defines the action, second provides use case context, third explains scoping and sibling relationship. 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 simple key-value retrieval tool with one optional parameter and good annotations, the description covers purpose, usage, and context. No output schema, but the return format is reasonably inferable. Adequately 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 covers both the key parameter and behavior (omit to list all keys). Description restates this without adding new semantics. With 100% 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?

Description clearly states the tool retrieves a saved value or lists all keys. Uses specific verbs ('Retrieve'/'list') and resource ('value previously saved via remember' or 'saved keys'). Distinguishes from siblings 'remember' and 'forget' by referencing them.

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

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

Explicitly says when to use: 'look up context the agent stored earlier' and 'without re-deriving it from scratch'. Mentions scoping. Does not explicitly state when not to use, but the pairing with remember/forget provides implicit guidance.

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

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

The description contradicts annotations: it describes mark_read:true as a state-changing operation (flagging events as read) while annotations declare readOnlyHint:true (no data modification). This is a serious inconsistency.

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

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

The description is concise (4 sentences), front-loaded with the main action, and every sentence adds necessary context without fluff.

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

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

Given no output schema, the description effectively explains return content (source, citation_uri, payload) and key behaviors (filtering, mark_read). It lacks pagination details but is otherwise complete for a read-oriented tool with good annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving examples (e.g., 'sec_8k' for type) and explaining the effect of mark_read and since parameters. It does not cover limit or unread_only explicitly, but those are in the schema.

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

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

The description clearly states the verb 'Pull' and the resource 'fired events from your subscription feed'. It specifies return fields (source, citation_uri, raw payload) and distinguishes itself from sibling tools by mentioning an alternative GET endpoint, though no direct sibling overlaps.

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 good usage guidance: filtering options, mark_read behavior, and polling suitability. It also mentions an alternative access method, but does not explicitly state when to avoid this tool.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds critical behavioral details: parallel fan-out to multiple sources, GDELT→GNews fallback on rate limits, USPTO soft-fail on plan, and return format (structured changes grouped by source with citation URIs). 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 front-loaded with query examples, then explains behavior and sources. Although lengthy, each part adds essential information. Could be slightly trimmed without losing clarity.

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

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

Given 3 required params, no output schema, and annotations covering safety, the description provides adequate context: data sources, fallback strategy, return structure, and sibling guidance. Missing pagination info, but acceptable for a change feed tool.

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

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

Input schema has 100% coverage for parameter descriptions, but the description adds value by clarifying that 'since' accepts ISO dates and relative shorthand, with recommended typical values ('30d', '1m'), and that 'value' accepts ticker or CIK. This goes beyond the schema's basic descriptions.

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

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

The description clearly defines the tool as a change feed for a company over a time window, listing specific data sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishing it from sibling entity_profile. The examples cover various phrasing alternatives.

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

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

Explicitly states when to use this tool vs entity_profile, provides example queries, and describes how the tool handles fallbacks. No ambiguity about scope or 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?

Discloses key behavioral traits beyond annotations: scope by identifier, persistence differences between authenticated (persistent) and anonymous (24 hours), and idempotency implied by the description of key-value storage. Annotations confirm idempotentHint and no contradictions.

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

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

Three sentences, each earning its place: first for purpose, second for usage context, third for behavioral and pairing details. No unnecessary words, well-structured and front-loaded with the core action.

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

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

Given the tool's simplicity (2 required params, no output schema), the description is complete. It covers what, when, how, persistence, and related tools. An agent has all necessary information to use 'remember' correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the purpose of the key-value pair ('findings, addresses, preferences, notes') and contextualizing the parameters within memory storage, which is slightly more than what the schema alone provides.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later...'. It uses specific verbs ('save', 'reuse') and resource ('data'), and effectively distinguishes from sibling tools like 'recall' and 'forget' which are explicitly mentioned.

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

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

Provides explicit guidance: 'Use when you discover something worth carrying forward...' and mentions pairing with 'recall' and 'forget' for retrieval and deletion. This directly helps the agent decide when to invoke 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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by disclosing internal cascading (replaces 2-3 manual lookups) and auto-disambiguation, which goes beyond what annotations 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 well-structured with examples first, then usage guidance, then type details. It is slightly verbose but every sentence adds value, and the key information is front-loaded.

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

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

With 2 required parameters and no output schema, the description covers inputs, outputs, and usage context well. It mentions citation URIs and replaces manual lookups, but lacks details on error handling or the exact JSON structure of the response.

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

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

Schema coverage is 100%, so the schema already describes both parameters. The description mostly repeats schema info but adds contextual details like 'auto-disambiguated' and specific examples (e.g., 'ozempic', 'metformin'), offering minor additional meaning.

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

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

The description clearly states the tool resolves a name to an official identifier, provides concrete examples ('What's the ticker for...'), lists supported types (company, drug) and their outputs (ticker, CIK, RxCUI, etc.), and is distinct from siblings by solving a specific name-to-ID problem.

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 FIRST whenever you have a name but need an ID,' giving clear context for when to invoke. However, it does not explicitly state when not to use it or compare it directly to sibling tools like entity_profile or compare_entities.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description does not contradict them. It adds behavioral detail about probing each entity with ai_visibility_check and handling the _apiKey parameter. However, it does not mention rate limits or potential costs.

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

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

Two concise sentences with no wasted words. The key purpose, method, and use case are front-loaded.

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

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

Given the tool's complexity (multi-entity comparison), annotations cover safety, and parameters are fully described, the description is complete. Although there is no output schema, the description specifies the return format (ranked list with score, confidence, signal density).

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that the first entity is treated as the subject for narrative and that context disambiguates common names. This goes beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check, and ranks results. It distinguishes itself from the sibling ai_visibility_check (single entity) by focusing on multiple entities and comparison.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question. It implies when to use this tool (multi-entity comparison) vs. ai_visibility_check (single entity), but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds critical behavioral context: bundlephobia's first measurement can take 5-30s and partial failures degrade gracefully (sources_failed list). No contradiction with annotations.

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

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

Description is somewhat lengthy but front-loaded with core purpose. Every sentence adds value, though slight condensation could improve conciseness without losing information.

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

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

No output schema, but description explicitly lists return fields (summary block, per-advisory detail, links, alternative versions). Also covers error handling (partial failures with sources_failed). Complete for a composite check 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 description adds meaning beyond schema: mentions scoped packages are accepted and version defaults to latest when omitted. This provides useful 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?

Description starts with a clear verb phrase 'Composite should I add this npm package to my project check in ONE call' and details what it fans out to (deps.dev and bundlephobia). It distinguishes itself from sibling tools (e.g., scan_competitor_ai_presence) by focusing on npm dependencies.

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

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

Explicitly states when to use: 'whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. Also clarifies scope: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing 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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds embedding model (BGE-base-en), chunking (500-char overlapping windows), length cap (200K chars with truncation flag), and mentions offsets and scores. This goes beyond annotations, though could clarify result ordering.

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

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

Six well-structured sentences with no filler. Each sentence adds value: purpose, use case, pairing, technical details, and constraints. Ideal length for quick comprehension.

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

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

Despite no output schema, the description explains return format (passages with offsets and scores) and mentions truncation behavior. For a search tool, this provides sufficient context for an agent to invoke correctly.

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

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

Schema description coverage is 100% with clear field descriptions. The description adds real-world context, such as natural-language query examples and the 200K char limit for text, enhancing understanding beyond the schema.

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

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

The description clearly states the tool does semantic search inside a previously fetched record, specifying verb 'search', resource 'fetched record', and distinguishing it from sibling tools like ask_pipeworx_grounded. It mentions returning passages with offsets and scores, making the purpose unmistakable.

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

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

Explicitly advises when to use: 'when the record is too big to cram into the prompt'. It also recommends pairing with ask_pipeworx_grounded and explains how to use it, providing clear context and alternatives.

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

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

The description adds significant behavioral context beyond annotations: returns a new ID, requires OAuth, type-specific params, delivery constraints (phone verification, SMS cap, webhook auto-disable after 10 failures). Annotations indicate idempotentHint=true, but the description does not clarify behavior on duplicate subscriptions. 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 moderately long but well-structured: purpose first, then requirements, then types, then delivery channels. Every sentence adds value, no waste. Could be slightly more compact but efficient overall.

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 3 parameters (2 required) and no output schema, the description covers subscription creation thoroughly: purpose, return value, requirements, type-specific parameters, delivery options with constraints. Missing idempotency detail and how to cancel via sibling, but sufficient for a complex tool.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds value by giving concrete examples for each subscription type in the params field and explaining webhook signing secret and auto-disable in the delivery field, enhancing understanding beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a new subscription ID. It lists supported types and delivery channels, distinguishing it from siblings like unsubscribe, list_subscriptions, and recent_alerts.

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

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

The description explicitly requires a Pipeworx OAuth account and notes that anonymous and BYO accounts cannot persist subscriptions. It details supported types with examples and delivery channel options including constraints (phone verification, 10/day cap, webhook auto-disable). However, it does not explicitly state when not to use 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?

Description adds context beyond annotations: it reveals the tool returns category-bucketed example questions with exact tool+argument shapes, drawn from a live catalog. Annotations already declare safe, non-destructive, idempotent behavior. The description enriches understanding without contradicting structured data.

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

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

The description is front-loaded with common user queries and is reasonably concise. It avoids verbosity, though the list of categories could be slightly trimmed. Every sentence serves a purpose: defining triggers, explaining output, and giving usage context.

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

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

Given no output schema, the description adequately explains the return type (category-bucketed example questions) and mentions the source (live catalog). For a discovery tool with rich annotations, this provides sufficient completeness. Could optionally detail pagination or response format, but current is adequate.

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% (only one optional parameter). The description adds meaning by explaining the effect of omitting vs. providing a topic, and lists the allowed focus areas with natural language equivalents. This goes beyond the schema's brief 'Optional focus area' description.

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

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

The description clearly defines the tool as an onboarding entry point that returns categorized example questions. It specifies the verb 'returns category-bucketed example questions' and distinguishes it from sibling tools like ask_pipeworx or entity_profile by focusing on teaching what can be asked.

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

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

Explicitly states when to use ('Use this FIRST when you do not yet know what Pipeworx can do') and provides guidance on arguments (no args for full spread, optional topic to focus). Also mentions learning how to call meta-tools, effectively guiding the agent on alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns monthly collection amounts, which is consistent and slightly extends behavioral context. No contradictions.

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

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

The description is a single, clear sentence that front-loads the action and resource. Every word is meaningful, 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?

The tool has one parameter, a rich annotations set, and an output schema. The description sufficiently covers the tool's purpose and result, making it complete for agent understanding.

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

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

The input schema has 100% coverage for the single parameter 'limit', including its description. The tool description does not add additional parameter details, so baseline 3 applies.

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

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

The description clearly states the tool tracks monthly US customs duty revenue and returns monthly collection amounts for analyzing tariff impact trends. It explicitly differentiates from sibling tools like treasury_debt, treasury_exchange_rates, and treasury_receipts.

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

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

The description mentions the purpose 'to analyze tariff impact trends,' providing clear context for when to use this tool. However, it does not explicitly state when not to use it or name alternatives.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds behavioral context by specifying the return content (total public debt over time) and the inclusion of historical data points, which goes beyond the annotation information.

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 consists of two concise sentences with no extraneous information. It front-loads the primary purpose and follows with the specific output, making it efficient and easy to parse.

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

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

Given the tool's simplicity (one optional parameter, no required params, comprehensive annotations, and an existing output schema), the description provides sufficient context: it identifies the data type (national debt over time) and the historical nature. No additional details are necessary.

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

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

Schema coverage is 100% with a single 'limit' parameter having a clear description and default. The tool description does not provide additional information about the parameter, so it neither enhances nor detracts from the schema.

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

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

The description clearly states the verb 'Check' and the resource 'US national debt with historical data points', and specifies that it returns 'total public debt outstanding over time'. This effectively distinguishes it from sibling treasury tools like treasury_customs_revenue or treasury_exchange_rates.

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

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

The description implies usage for debt-related queries but does not explicitly state when to use this tool versus other treasury siblings. No exclusion criteria or alternative tool mentions are provided.

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. Description adds minimal behavioral context ('Returns rates used for government conversions') but doesn't contradict annotations.

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

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

Single sentence is concise and front-loaded, but could be more precise about the input parameter. No unnecessary text.

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

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

Output schema exists, but the description fails to explain how the 'country' parameter relates to exchange rates or currencies. The 'limit' parameter is not mentioned. Incomplete for a tool with 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%, so baseline is 3, but the description misleads by using currency examples (EUR, GBP) while the required parameter is 'country' (e.g., China). This adds confusion rather than meaning.

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

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

Description clearly states it returns US Treasury exchange rates for government conversions, distinguishing from sibling treasury tools. However, it mentions currency codes (EUR, GBP) while the required parameter is 'country' (e.g., China), creating a mismatch that reduces 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?

No guidance on when to use this tool versus alternatives. Lacks context about the relationship between country and currency, and does not mention when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false, covering safety and idempotency. The description adds no new behavioral traits beyond restating the purpose, so it provides minimal additional transparency.

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

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

The description is a single, well-structured sentence that is front-loaded with the verb. It is concise with no wasted words, efficiently conveying the tool's purpose.

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

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

Given the presence of an output schema, annotations, and a single parameter, the description adequately covers the core purpose and example sources. However, it could briefly mention data scope (e.g., time period) for added clarity, but overall is complete for a simple read tool.

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

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

Schema description coverage is 100% for the single 'limit' parameter, which is described with default value. The tool description does not add any further meaning about parameters, so it meets the baseline but does not enhance parameter understanding.

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

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

The description uses the specific verb 'Get' and clearly identifies the resource as 'US government receipts by source', listing example sources like individual income tax and corporate tax. This clearly distinguishes it from sibling tools such as treasury_customs_revenue (focused on customs) and treasury_debt (debt, not receipts).

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., treasury_customs_revenue for customs-specific data). The description simply states what the tool does without any usage context or 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 notes that the row is deactivated (not deleted) and historical events remain available, which aligns with the destructiveHint=false annotation. It adds context about ownership enforcement 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 two sentences with no extraneous information. The main action is stated first, and additional constraints are provided efficiently.

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 mutation with one parameter and no output schema, the description covers the action, ownership constraint, and deactivation behavior comprehensively. It explains the effect on historical data, making it complete for the agent's 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 provides a description for the 'id' parameter ('Subscription id (uuid) returned by subscribe.'), achieving 100% coverage. The description adds no additional parameter-level detail, so a baseline score of 3 is appropriate.

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

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

The description starts with 'Cancel a subscription by id,' clearly stating the action, resource, and identifier. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by specifying it's for cancellation.

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

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

It explicitly says 'you can only cancel your own subscriptions,' providing a clear usage constraint. It also mentions the effect on historical data via 'recent_alerts,' but does not explicitly state when not to use this tool.

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

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

Annotations declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral context: it returns a verdict with structured form, actual value with citation, and percent delta. It also mentions that v1 supports only company-financial claims, indicating future expansion. 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 very concise: two sentences front-loaded with key phrases. Every sentence adds value, describing purpose, domain, and output summary. No wasted words.

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

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

Given the single parameter, no output schema, and safe annotations, the description is complete. It explains input format, supported domain, output structure, and even compares to alternative approaches (replacing multiple calls). There are no significant gaps for an agent to use this tool effectively.

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

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

Schema coverage is 100%, so the description does not need to add much. The parameter 'claim' is already well-described in the schema with examples. The description reinforces the natural-language nature and usage context, but this adds limited new semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with specific trigger phrases and domain (company-financial claims). It distinguishes this tool from siblings by focusing on fact-checking, which no other sibling tool does.

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

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

The description explicitly says to use it when the agent needs to check factual correctness. It limits the domain to US company-financial claims and notes it replaces multiple sequential calls, providing some guidance. However, it does not give instructions for when not to use it or alternatives for non-financial claims.

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