Dev Feeds

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral details: per-model return fields (score, confidence, signals, raw_response), combined view, billing implications (free vs BYO key). 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 a single focused paragraph of 4 sentences. Main purpose is stated upfront, every sentence adds value, no redundant information.

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

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

Covers all key aspects: what it does, return structure, optional parameters, billing. Although no output schema exists, the description explains output fields. Lacks example of output format, but adequate for most use cases.

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

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

Schema coverage is 100% with descriptions, but the tool description adds context beyond schema: default model, pricing model for Anthropic, and purpose of the 'context' parameter for disambiguation.

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

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

The description states a specific verb ('probe', 'score') and resource ('LLMs') with a clear outcome ('visibility score 0-100 per model'). It distinguishes from siblings like 'deep_research' or 'entity_profile' by focusing on multi-model visibility auditing.

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

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

Explicitly mentions use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to pass the Anthropic key. However, it does not exclude cases where sibling tools might be more appropriate.

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

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

Annotations already indicate readOnly, openWorld, idempotent. The description adds that it returns structured answers with citation URIs, routes questions, and fills arguments. No contradictions, and it enriches the behavioral model.

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 the key instruction ('PREFER OVER WEB SEARCH') and provides examples. Some redundancy exists (e.g., listing many domains twice), but overall efficient for the complexity.

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

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

Given the tool's wide scope (4482 tools, 1129 sources) and the absence of an output schema, the description provides all necessary context: use cases, alternatives, return format, and examples. It is self-contained and leaves no major gaps.

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

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

Schema coverage is 100% with descriptions for each alias. The description adds value by clarifying that the parameter is a natural language question and explaining the tool's routing behavior, which helps the agent understand how to use the parameter.

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

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

The description clearly states it answers factual questions across many domains, routing to thousands of tools. It distinguishes from siblings like ask_pipeworx_grounded and deep_research, making the tool's purpose unambiguous.

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

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

Explicitly tells when to use (over web search, for factual questions) and when to step up (grounded for evidence, deep research for broad questions). Provides concrete examples, leaving no ambiguity.

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

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

The description discloses the tool's behavior beyond annotations: it routes through 4,482 tools, fills arguments, fetches data, and returns a structured response with evidence, refusal reasons, and source. This is consistent with the readOnlyHint, idempotentHint, and destructiveHint annotations, and adds crucial cost and reliability 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 front-loaded with the core identity, then efficiently covers routing, return format, and usage guidance. Every sentence adds distinct value; there is no redundancy or filler.

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

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

Given the complexity (many sibling tools, multiple aliases, and no output schema), the description covers purpose, behavior, return format, failure modes, and cost tradeoffs. It is fully sufficient for an agent to understand and invoke the tool correctly without additional context.

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

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

Although the schema fully describes the parameters (all aliases for 'question'), the description adds behavioral context by explaining that the question is used to route to 4,482 tools and fill arguments. This extra meaning justifies a score above the baseline of 3, but not a 5 because the parameter itself is simple and well-documented.

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

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

The description clearly identifies the tool as a 'Hallucination-resistant answer mode for high-stakes reads,' specifying its function of extracting answers solely from tool results. It distinguishes itself from the sibling 'ask_pipeworx' by noting the extra LLM call cost and the grounded extraction process.

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

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

The description explicitly states when to use the tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples like financial verdicts or medical lookups. It also advises against casual use, recommending 'ask_pipeworx' instead, providing clear 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 read-only, idempotent, non-destructive. The description adds extensive behavioral details: fan-out logic, resolution confidence handling, parent event extraction, news fallback, safety short-circuits, closed market handling, wide-spread warnings, and resolution-rule risk. No contradictions.

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

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

The description is long but well-structured with sections, examples, and front-loaded core purpose. Every part adds value given the tool's complexity, though it could be slightly more concise.

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

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

Given the tool's complexity (classifiers, fan-out, response shapes) and no output schema, the description is remarkably complete: it covers input, classifiers, examples, response structure, resolver contract, parent events, news fallback, safety, and resolution-rule risk.

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 parameters are documented. The description adds context on input formats (slug, URL, question text) and explains the 'depth' and 'include_raw' parameters, providing additional meaning beyond schema descriptions.

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

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

The description clearly states the verb ('research'), resource ('Polymarket bet'), and mechanism ('pull Pipeworx data in one call'). It distinguishes from siblings by focusing on research rather than arbitrage or edges.

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

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

The description provides explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') but does not explicitly state when not to use or mention alternatives among 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?

Beyond annotations (readOnlyHint, idempotentHint), the description explains data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, and that results are sorted by primary metric. No contradiction with annotations.

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

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

The description is dense with valuable information but lacks structural formatting like bullet points. It is front-loaded with query examples, which helps, but the paragraph style reduces scannability.

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 entity types, data sources, number of entities, output format (paired data + citation URIs), and performance benefit. No output schema, but the description adequately describes results. Complete for a comparison tool.

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

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

Schema coverage is 100%, but the description adds meaning by detailing what data each type retrieves (e.g., revenue, net income for companies; adverse-event counts for drugs) and clarifying the 'values' parameter with examples and limits.

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 performs side-by-side comparisons of 2-5 companies or drugs, with specific metrics per type. It provides query examples and distinguishes from sibling tools like entity_profile by emphasizing parallel data retrieval.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' directly guiding when to use this tool vs alternatives. It also specifies the number of entities (2-5) and entity types.

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 safe, read-only operation. The description adds substantial context: parallel tool routing across 4,482 tools, return format (verbatim evidence with confidence/source/citation, gaps array), expected latency (15-60s), and the nature of data sources. 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 fairly lengthy but well-structured, front-loaded with critical account info and alternatives. Each sentence adds value, though some trimming could improve conciseness without losing information.

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

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

Given the tool's complexity (2 parameters, no output schema, but rich annotations), the description covers the return format, limitations, latency, and appropriate use cases. It feels complete and leaves no major questions unanswered.

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

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

With 100% schema coverage, the description enriches both parameters: explains the depth enum values with defaults and paywall, and clarifies that the question parameter can be broad/multi-part. This adds practical 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 clearly states the tool does grounded multi-source research across 1129 structured data sources, distinguishing it from siblings like ask_pipeworx for single lookups or current news. It uses specific verbs and resources, making the purpose unambiguous.

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

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

Explicitly states when to use (broad/multi-part questions over structured data), when not to use (lack of account, breaking news), and provides alternatives (ask_pipeworx). Also mentions account requirements and paid plan for 'thorough' depth.

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 readonly, idempotent, non-destructive. Description adds that it returns top-N tools with schemas and curated examples, each result ready to call directly. No contradiction. Adds significant behavioral context beyond annotations.

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

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

Two sentences, but first sentence is a long list of domains. Could be more concise, but structure is front-loaded and effective. Every part adds value.

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

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

Despite 6 params and no output schema, description covers purpose, usage, return value (top-N tools with schemas), and result usability. Complete 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% (all parameters described). Description adds value by stating return format (top-N, ready to call) without repeating schema. Baseline 3, but extra context justifies 4.

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

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

Description clearly states it finds tools by describing data or task, lists many domains (SEC, FDA, etc.), and distinguishes from siblings by saying 'call this FIRST'. Purpose is explicit and specific.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and advises calling this first when many tools available. Lacks explicit 'when not to use' but context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant context about fanning out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), specific return fields (cik, recent_filings, fundamentals, patents, etc.), and a known failure mode (patents soft-fail after May 2025). 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 thorough but somewhat lengthy, mixing examples, behavioral notes, and return details in one paragraph. While every sentence adds value, it could be more structured (e.g., bullet points) for easier scanning. Still, it is front-loaded with the main action and examples.

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-source profile) and the absence of an output schema, the description provides a detailed breakdown of what is returned (fields, sources, URIs, sorting). Combined with annotations that cover safety and idempotency, there are no significant gaps for an agent to invoke this tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reinforces this by specifying that 'value' accepts ticker or zero-padded CIK and explicitly says names are not supported, and 'type' is currently limited to 'company'. This goes slightly beyond the schema by providing usage context but does not add entirely new semantic information.

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 'full cross-source profile of a US public company in ONE parallel call' with specific verb 'profile' and resource 'US public company'. Examples like 'Tell me about X' and 'company profile for Microsoft' reinforce the purpose and distinguish it from sibling tools.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. Also tells when not to use: 'names not supported (use resolve_entity first if you only have a name)' and mentions soft-fail for patents.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds transparency about network resilience (CF-robust, proxy fallback) beyond annotations, but does not detail return format or error handling.

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 concise sentences front-load the main purpose, then add behavioral context and usage hint. No waste.

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

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

For a 3-parameter fetch tool with strong annotations, the description covers purpose, behavior, and usage guidance adequately. No output schema needed explanation of return values.

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 does not add significant meaning beyond the schema's parameter descriptions; it merely restates the URL pattern and default limit.

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 fetches and normalizes RSS/Atom/RDF feeds by URL, which is specific and distinct. It also contrasts with list_feeds for curated sources, implying a use case for arbitrary URLs.

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 to use list_feeds first for curated sources and notes CF-robust behavior with proxy fallback. However, it does not compare directly with sibling read_feed or 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 already indicate destructiveHint=true and readOnlyHint=false, so the description's 'Delete' adds no new behavioral disclosure. No mention of side effects or error behavior.

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

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

Two efficient sentences: one stating purpose, one giving usage guidance and pairing suggestions. 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?

No output schema, but description implies deletion without details on confirmation or error handling. Understandable for a simple tool, but could be more explicit about idempotency or return values.

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

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

Schema coverage is 100%, so baseline is 3. Description mentions 'by key' but adds no additional meaning beyond the schema's parameter 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?

Clearly states 'Delete a previously stored memory by key' as the verb and resource. Distinguishes itself from sibling tools 'remember' and 'recall' by specifying deletion.

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

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

Provides explicit usage contexts: 'when context is stale, the task is done, or you want to clear sensitive data'. Lacks explicit exclusion or alternative tool guidance, but implicitly contrasts with 'remember' and 'recall'.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that it fetches the page, extracts title/description/key links, and emits markdown. This is consistent and adds useful detail.

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

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

Three sentences with no unnecessary words. Front-loaded with the core purpose, then lists use cases. Every sentence adds value.

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

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

For a tool with 2 parameters, no output schema, and simple behavior, the description covers purpose, usage, and basic behavior. No gaps for an AI agent to misinterpret.

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

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

Schema coverage is 100% with descriptions for both parameters. The description confirms defaults (max_links: 25, max 50) but does not add significant new meaning 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 it generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and the resource 'llms.txt'. It distinguishes from sibling tools by focusing on a specific output format and 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 explicitly lists three use cases: getting a client's site indexed, drafting for own projects, and auditing competitor pages. Though it lacks explicit when-not-to-use, the context is clear enough for an AI agent.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds context about curated feeds and fields returned, but no additional behavioral details (e.g., pagination, rate limits).

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 succinct sentences: first defines core functionality, second adds filters and cross-reference. No redundant info.

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 specifies returned fields (id, title, category, source). Sufficient for a list tool with optional filters and no required parameters. Minor omission: no mention of pagination or ordering.

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

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

Schema coverage is 100% with clear descriptions for both parameters. Description reiterates optional filtering but doesn't add meaning beyond the schema. Baseline 3 is appropriate.

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

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

Description uses specific verb 'list' and resource 'feeds', enumerates returned fields (id, title, category, source), and mentions optional filters. Clearly distinguishes from siblings like read_feed.

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 optional filters and directs users to read_feed for a specific feed. However, lacks discussion of when to use vs other siblings like fetch_feed or list_subscriptions.

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, establishing safety. The description adds value by listing return fields and the optional include_inactive parameter, clarifying what data is retrieved. No contradictions.

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

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

Two sentences plus a field list, no wasted words. The main action and return structure are upfront, and every sentence serves a purpose.

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

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

Given no output schema, the description adequately covers return fields and usage. It could explicitly state the output is an array, but the description's detail is sufficient for an agent to understand the tool's function and output.

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

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

Schema coverage is 100% with the include_inactive parameter well-described in the schema. The description does not add additional meaning beyond repeating the field list. 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 lists the caller's active subscriptions, specifying return fields. It distinguishes from siblings like subscribe and unsubscribe by focusing on listing existing subscriptions.

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

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

The description explicitly advises using this tool to review monitoring before adding more subscriptions or to find an id to cancel. It provides clear context for when to use it, though it doesn't 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 provide no hints (all false), but the description adds important behavioral details: rate-limited to 5 per day, free, doesn't count against tool-call quota, and team reads daily. This goes beyond the annotations.

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

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

The description is front-loaded and uses concise, informative statements. Every sentence adds value, with no waste. The structure is easy to parse for an AI agent.

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

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

For a simple feedback tool with three parameters and no output schema, the description covers all necessary aspects: purpose, when to use, parameter details, constraits, and processing pipeline. No gaps remain.

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

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

Schema has 100% coverage of parameters, but the description adds value by explaining the 'type' enum in more detail and providing usage guidance for 'message' (be specific, 1-2 sentences, 2000 chars max). It also clarifies the optional context structure.

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

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

The description clearly states it is for sending feedback about broken, missing, or needed items. It distinguishes itself from sibling tools, which are all for querying or information retrieval, by being the sole feedback tool.

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

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

Explicitly tells when to use (bug, feature, data_gap, praise) and what not to do (avoid pasting end-user prompts). It does not directly name alternative tools, but the sibling list makes it clear this is the feedback channel.

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 no destructiveness. Description adds valuable behavioral details: data is self-aggregating from CF analytics-engine, no PII involved, and caching varies by window (5min-1h). This goes 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?

Three sentences, each with a distinct purpose: first describes output, second lists use cases, third notes caching and data origin. No wasted words, front-loaded key info.

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

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

For a simple read-only tool with one parameter and no output schema, the description fully covers purpose, usage context, data source, caching behavior, and output structure (top tools, top packs, total call volume). 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?

Single parameter 'window' has full schema description coverage. Description adds semantic guidance: shorter windows show hot trends, longer windows show steady-state demand. This enhances understanding beyond the enum values.

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

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

Description clearly states it returns top tools, top packs, and total call volume over a recent window. The verb 'returns' is specific, and the resource 'Pipeworx trending' is well-defined. It distinguishes itself from sibling tools like 'discover_tools' or 'ask_pipeworx' by focusing on aggregated trending data from other AI agents.

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 provides three explicit use cases: discovering hot data sources, confirming canonical tools, and aligning use cases. Though it doesn't specify when not to use, the given contexts are clear and practical. The read-only, idempotent nature makes it broadly applicable, but alternatives are not mentioned.

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

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

Annotations indicate read-only, open-world, and idempotent. The description adds extensive behavioral details: semantic anchor with Jaccard similarity, partition filter for placeholder slugs, fill check against live CLOB depth, and conditions for not trading. 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 well-structured with clear sections and front-loaded requirement. Every sentence adds value, covering modes, semantic checks, response format, and fill check. It is dense yet highly readable.

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

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

Despite no output schema, the description fully explains response fields (opportunities[], partition_check, fill check). It covers edge cases (Jaccard similarity, placeholder fraction) and references a sibling tool for additional functionality. Complete for the tool's complexity.

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

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

Schema description coverage is 100% with both parameters described. The description adds significant meaning beyond the schema, including examples of slugs and seed questions, accepted formats (full URLs), and detailed behavior for each parameter.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes between two modes: 'event' for single-event and 'topic' for cross-event scanning, making the purpose explicit and precise.

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

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

The description explicitly says when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It warns that calling with no args fails and references a sibling tool for custom sizing, providing clear usage guidance.

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

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

Description goes far beyond annotations (readOnlyHint, idempotent) by detailing internal model families, filter knobs, caching behavior (1h KV), response structure (by_segment, diagnostics), and tradeable-edge knobs. It discloses that Fed bets surface separately and are excluded from ranking, and explains why partition_overround opportunities have null parent Kelly. 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 very verbose, spanning multiple paragraphs of dense technical detail. While each sentence is informative, the lack of bullet points or section breaks makes it harder to scan quickly. The front-loading with the main purpose is good, but the subsequent model-family deep dive could be condensed or moved to documentation. It could be more concise for an AI agent.

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

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

The description is fully complete for a complex tool with 9 parameters, no output schema, and no sibling overlap. It explains response structure (by_segment, diagnostics), caching, filter knobs, tradeable-edge filters, and even warns that Fed bets are excluded and why. An agent has enough information to decide when to call this tool and how to interpret results.

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

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

Schema coverage is 100% with detailed parameter descriptions, so baseline is 3. The description adds value by explaining how knobs interact (e.g., min_partition_leg_kelly applies to per-leg Kelly in top_legs, not parent level), clarifying the meaning of 'edge' and 'slippage', and providing context on volume windows. It compensates beyond the schema but does not dramatically increase clarity since schema is already thorough.

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+resource+goal: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It explicitly states the tool is built for 'what should I bet on today' and distinguishes from sibling tools like polymarket_arbitrage by focusing on Pipeworx disagreement and broad market scanning, not specific arbitrage or tracking.

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

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

The description provides clear context for when to use the tool ('what should I bet on today', 'discover opportunities without paging hundreds of markets'), but does not explicitly state when not to use it or mention alternatives among sibling tools. It implies this is the primary discovery tool, but lacks explicit exclusions or guidance on switching to other tools like polymarket_arbitrage for specific cross-market opportunities.

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

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

The description adds significant behavioral context beyond annotations: it details what tracked, expired, and snapshot dates mean, as well as limitations like the 60-day TTL. This complements annotations (readOnlyHint, idempotentHint) 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 slightly verbose but well-structured with clear sections (Args, RESPONSE, LIMITS). It front-loads the purpose and provides essential details without being wasteful.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and behavioral nuances, making it complete 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?

Both parameters are fully described in the schema, but the description adds context like 'snapshot family' and default values, enhancing understanding beyond the schema alone.

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 provides 'edge persistence and decay telemetry' and answers a specific question about edge age and shrinkage. It distinguishes itself from sibling tools like 'polymarket_edges' by focusing on historical tracking and decay analysis.

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

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

The description explains when to use the tool: to understand edge age and decay trends, contrasting fresh vs old wide edges. It mentions limitations (e.g., decay from daily closes) but does not explicitly state when not to use or provide direct alternatives.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details behavioral aspects: ladder walking, returned fields (top_of_book, vwap_fill_price, slippage, etc.), basket mode behavior, and warnings about thin books and forced directional risk.

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

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

The description is long but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, final note). Every sentence adds value; no fluff. Could be slightly shortened but acceptable given 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 no output schema, the description comprehensively lists return fields for both modes and explains edge cases (thin_legs, forced_directional_risk). It also ties into sibling tool usage, making it self-contained for an agent to decide 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%, but the description adds context: side default behavior in basket mode (auto from partition sum), interpretation of size_usd (settlement notional for basket, spend/proceeds for single-market), and required presence of market or event. This goes 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 checks 'realizable-vs-theoretical edge against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It explicitly differentiates from sibling tools by specifying usage before acting on polymarket_arbitrage signals or large polymarket_edges trades.

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 guidelines: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the risk of partial fills and unhedged directional positions, indicating when not to proceed.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral context: safety fields (compatibility_warning, temporal_alignment, skipped counters), conditions for meaningful spreads, and a note on rarity. 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 well-structured: purpose, modes, response, safety fields, closing note. While lengthy, every sentence adds value and the organization aids readability. Minor verbosity could be trimmed but overall effective.

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

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

Despite lacking an output schema, the description thoroughly explains return values (leg-by-leg prices, top_spreads_pp, safety fields) and input options. It covers all necessary context for an agent to invoke the tool correctly, including edge cases and warnings.

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

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

All three parameters have schema descriptions (100% coverage). The description further explains the two modes and lists valid topic values, adding clarity beyond the schema. It does not, however, detail the format of ticker/slug values beyond examples.

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

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

The description clearly defines the tool as computing cross-venue spreads between Kalshi and Polymarket, specifying two modes (topic shortcuts and explicit pairings). It distinguishes itself from sibling tools like polymarket_arbitrage by being cross-venue, and the verb+resource combination is precise.

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

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

The description explains when to use the topic mode vs explicit mode, and provides detailed conditions for valid spreads (temporal alignment, bet shape equivalence). It warns that most pre-mapped topics yield compatibility warnings, setting realistic expectations. However, it does not explicitly compare to sibling tools.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description does not need to repeat those. It adds value by listing normalized return fields (title, link, published, summary) and optional keyword filtering, which are not in annotations.

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

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

Two sentences containing essential information: action, resource, source, return fields, and optional filter. No redundancy or irrelevant details.

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

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

With no output schema, the description covers return fields. However, it lacks details on pagination, sorting, and behavior when limit or query are omitted. The annotations satisfy safety and idempotency, so the gap is minor.

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

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

Schema coverage is 100%, so baseline 3. The description reinforces the feed id's origin and adds minimal detail for the query parameter, but does not add new meaning beyond the schema descriptions. The limit parameter is not mentioned in the description.

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

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

The description clearly states the verb 'read', the resource 'curated software-development feed', and the required identifier from list_feeds. It distinguishes from siblings like fetch_feed by specifying 'curated' and sourcing from list_feeds.

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 context by referencing list_feeds for the feed id, but does not explicitly state when to use this tool versus alternatives like fetch_feed or other sibling tools. No when-not guidance is 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 readOnlyHint and destructiveHint; description adds valuable context about scoping to identifier and behavior of omitting key to list all. Could mention pagination or return format but adequate.

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 efficient sentences, front-loaded with the primary action, 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 no output schema, description explains return behavior (value or list), scoping, and pairing with remember/forget. Fully adequate for a simple retrieval tool.

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

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

The only parameter 'key' is fully described, including the important semantic that omitting it lists all keys. Schema coverage is 100%, and description adds meaningful behavior beyond schema.

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

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

The description clearly states the verb (retrieve/list all), resource (previously saved values via remember), and distinguishes from siblings (remember, forget).

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

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

Provides explicit context for when to use (look up stored context without re-deriving) and implies alternatives via sibling pairing. Lacks explicit when-not-to-use but is clear enough.

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

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

The description states that setting mark_read:true 'flag[s] returned events read so the next call only shows newer ones,' indicating a state-modifying side effect. This directly contradicts the annotation readOnlyHint=true, which implies no state change. Therefore, the description contradicts the annotations, scoring 1 per rubric.

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

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

The description is concise (5 sentences) and well-structured. It opens with the core purpose, then details return fields, filtering, mark_read behavior, and a polling/script alternative. Every sentence is informative with no redundancy. It is appropriately front-loaded.

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

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

Given no output schema, the description adequately describes return fields (source, citation_uri, raw event payload). It explains parameter effects (type, since, mark_read) and provides guidance on polling and alternative access. All relevant aspects for correct invocation are covered, including side effects and external URL.

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

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

The input schema has 100% description coverage, providing baseline of 3. The description adds behavioral context beyond the schema, particularly for mark_read ('flag...read so the next call only shows newer ones') and provides an example filter value ('sec_8k'). It does not cover unread_only or limit, but the schema descriptions suffice. Overall, it adds meaningful value.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It defines the resource (subscription feed alerts) and action (pull/recent alerts). It distinguishes from sibling tools like fetch_feed by specifying it returns only recent alerts with specific fields and provides an alternative direct URL for scripts.

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 usage context: it explains that polling works fine and that the same feed is available via a GET URL for scripts. It details filtering options (type, since) and the mark_read flag to manage read state. However, it lacks explicit guidance on when not to use this tool versus alternatives like fetch_feed or read_feed, and does not mention prerequisites.

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 fan-out to multiple sources, fallback logic (GDELT→GNews), soft-fail for USPTO due to API sunset, and return structure. Annotations already declare readOnlyHint and idempotentHint, and description adds rich behavioral context 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?

Description is comprehensive and front-loaded with example queries. However, it is somewhat dense and could benefit from brief bullet points to improve scanability, but every sentence is valuable.

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

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

Given no output schema, description fully explains return structure (changes grouped by source, total_changes, citation URIs). Covers behavior for all sources, parameter nuances, and corrects misconceptions (e.g., soft-fail). Complete and self-contained.

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

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

Schema coverage is 100%, but description adds significant meaning: explains since format with examples (ISO date and relative shorthand), clarifies type only supports 'company', and notes value accepts ticker or CIK. Recommends typical monitoring values.

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

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

Description clearly states purpose: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It includes specific verb, resource, and scope, and distinguishes from sibling tool entity_profile.

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

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

Explicitly advises when to use alternative: 'Use entity_profile instead when you want the static profile...' Also provides example queries ('What's new with X', 'latest on Y') indicating typical usage.

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

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

Annotations declare idempotentHint=true, destructiveHint=false. Description adds scoping details (identifier-based, persistent vs. 24-hour) beyond annotations. 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?

Four sentences, no wasted words, front-loaded with purpose. Efficiently covers purpose, usage, behavior, and related tools.

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 needed for a store operation. Description sufficiently covers scope, persistence, and pairing with recall/forget. Agent can confidently invoke.

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

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

Schema has 100% coverage with descriptions for key and value. Description reinforces with naming conventions and value types, adding value beyond schema.

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

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

Explicitly states it saves data for later reuse, lists examples (ticker, address, preference), and distinguishes from siblings recall and forget.

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

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

Provides clear when-to-use guidance ('when you discover something worth carrying forward'), contrasts with recall and forget, and mentions auth and session duration constraints.

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 safe, idempotent, read-only behavior. The description adds that each call internally cascades through multiple endpoints, replacing 2-3 manual lookups, and details the returned data per type. This is valuable context beyond the annotations.

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

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

The description is well-structured with front-loaded examples and a clear usage directive. It is moderately sized but each sentence adds value; minor redundancy in listing return types 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 no output schema, the description compensates by detailing returns per type. It covers supported types thoroughly but omits error handling or ambiguity resolution. Overall, it provides sufficient context for an agent.

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

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

Schema coverage is 100% with descriptions. The description expands by explaining the return values for each entity type, linking parameters to outputs. Examples enhance understanding beyond the schema alone.

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 names to canonical identifiers, with specific examples. However, it does not explicitly distinguish from sibling tools like compare_entities or entity_profile, though the use case is clear.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID', providing strong when-to-use guidance. Does not mention when not to use or alternatives, but the directive is sufficient for an agent.

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

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

Annotations provide readOnlyHint and idempotentHint. Description adds that output is a ranked list with score, confidence, and signal density per entity, and that first entity is treated as subject. 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?

Three sentences: first states purpose, second explains mechanism, third provides use case and return format. No fluff, 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?

Description covers output fields and relation to ai_visibility_check. Does not address sibling 'compare_entities' but overall complete for its complexity. No output schema, but description compensates adequately.

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 meaning beyond schema: explains that first entity in array is subject, context disambiguates common names, and models specify 'workers-ai' default vs 'anthropic' with API key requirement.

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 compares AI visibility across multiple entities side-by-side, with specific verb 'compare' and resource 'AI visibility'. Distinguishes from sibling 'ai_visibility_check' by emphasizing multi-entity comparison and ranking.

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 usage context: 'useful for competitive AI-marketing audits' with explicit question 'does Claude know about us as well as our competitors?'. Does not exclude alternatives or state when not to use, but context is clear.

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

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

Annotations already indicate read-only and idempotent behavior, but the description adds crucial context about partial failures: bundlephobia's first measurement can take 5-30s and sources_failed field lists timeouts. This goes 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 dense with useful information but slightly verbose. It front-loads the core purpose effectively, though could be trimmed slightly without losing substance.

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 lists all major return components (summary block, per-advisory detail, links, alternative versions). It also covers ecosystem limitations and timeout behavior, making it complete for the tool's complexity.

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

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

Schema has 100% description coverage for both parameters. The description adds value by noting that scoped packages like @types/node are accepted and explaining the version defaulting behavior.

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

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

The description clearly states it is a composite check for npm packages, covering license, advisories, version history, and bundle size. It distinguishes itself by specifying the NPM-only scope and mentioning alternatives for other ecosystems.

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

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

Explicitly says to use when agent asks about safety, popularity, size, or cost of adding a package. Also indicates when not to use: for non-NPM ecosystems, use deps.dev:version directly.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds specifics: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging. 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 concise (4 sentences) and front-loaded with the core purpose. Every sentence adds distinct information: purpose, when to use, technical details, and pairing. 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?

Even without an output schema, the description explains what is returned (top-N passages with character offsets and similarity scores). It also covers edge cases (truncation), embedding details, and chunking strategy, making it complete for an agent to understand 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?

Schema coverage is 100% with descriptions for all three parameters. Description adds value with examples for query ('supply-chain risk', 'fiscal year 2024 revenue'), clarifies text is 'document text', and explains limit is max passages (1-20, default 5).

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific examples (SEC 10-K, article). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and fetching with the gateway.

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: 'Use when the record is too big to cram into the prompt' and notes it saves context. Also mentions pairing with ask_pipeworx_grounded for grounded responses. Provides clear when-not-to-use guidance by implication.

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 details delivery channel behaviors (SMS cap, webhook auto-disable, signing secret). It notes OAuth requirement, aligning with annotations. No contradiction with annotations (idempotentHint: true is not contradicted). Does not explicitly mention idempotency or rate limits, but adds substantial behavioral context beyond annotations.

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

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

The description is well-structured with a clear first sentence stating purpose, followed by prerequisites, supported types, and delivery details. It is somewhat lengthy but each sentence adds necessary 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?

Without an output schema, the description explains the return value (subscription id). It covers prerequisites, all parameters, and delivery options comprehensively. It doesn't cover listing or management, which are handled by sibling tools.

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 significant value by providing examples and constraints for each parameter (e.g., type-specific params, SMS verification, webhook signing). 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 states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the return value (subscription id), prerequisites (OAuth account), and lists supported types with examples, distinguishing it from sibling tools like list_subscriptions.

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

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

The description provides clear context on when to use the tool (proactive monitoring, persistent subscriptions) and prerequisites (OAuth account). It doesn't explicitly state when not to use it, but the detailed type and delivery options imply appropriate use cases.

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 safe read-only, idempotent, non-destructive behavior. The description adds that results are drawn from a live catalog and that calling without arguments returns a full spread, adding context beyond annotations.

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

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

The description is moderately long but well-structured with front-loaded purpose, then details. Almost every sentence adds value, though it could be slightly tighter 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?

For a simple tool with one optional parameter and no output schema, the description is complete: it explains what the tool does, when to use it, argument behavior, and expected output, leaving 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 covers the 'topic' parameter fully (100% description coverage). The description adds examples of valid values ('finance', 'pharma', etc.) and clarifies that omitting the argument gives a cross-category spread, going 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 serves as the onboarding entry point, listing trigger phrases like 'What can I ask Pipeworx?' and explaining it returns category-bucketed example questions with tool calls. It distinguishes itself from sibling tools by being the initial discovery tool.

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

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

The description explicitly advises using this tool first when the agent doesn't know Pipeworx's capabilities, and explains when to omit or pass the 'topic' argument. It provides concrete guidance on invocation 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?

The description explains that the row is deactivated (not deleted), preserving historical events—adding context beyond annotations. Annotations already indicate non-destructive and idempotent, which aligns with the description.

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 that efficiently convey the action, constraint, and behavioral consequence with no wasted words.

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

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

For a simple tool with one parameter and no output schema, the description fully covers the purpose, usage constraint, and data lifecycle, making it complete for agent invocation.

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

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

The schema already fully describes the single parameter 'id' with its type and source. The description adds ownership context but does not enhance parameter-specific meaning 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 action 'Cancel a subscription by id.' This distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description provides clear ownership enforcement ('you can only cancel your own subscriptions') and the deactivation behavior. However, it lacks explicit when-not-to-use guidance or alternatives for permanent deletion.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, indicating safe read-only behavior. The description enriches this by detailing the data source (SEC EDGAR + XBRL), return values (verdict, actual value, citation, delta), and version limitations ('v1 supports company-financial claims'). 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 moderately detailed but front-loaded with purpose and examples. Every sentence serves a purpose: defining the tool, usage, domain, and output. It is not excessively long for the information conveyed, striking a balance between conciseness and completeness.

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

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

Given no output schema, the description fully explains the return format (verdict types, actual value with citation, percent delta). It covers domain limitations, references the underlying technology, and clarifies the tool's scope. This is complete for a single-parameter tool with rich 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?

The input schema covers the single 'claim' parameter with a description. With 100% schema coverage, the baseline is 3. The description adds extra meaning by providing examples of valid claims and explaining the tool's domain, enhancing the agent's understanding of what constitutes a suitable input.

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 validates natural-language claims against authoritative sources, with specific examples like 'Is it true that...' and 'fact check'. It distinguishes from siblings by specifying the domain (company-financial claims) and noting it replaces sequential calls, making its unique purpose evident.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' This provides clear context for usage. While it doesn't list when not to use or alternatives, it implies efficiency over sequential methods, and the sibling list exists for comparison.

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