Ship On Friday

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: the default model is free, Anthropic requires a user-provided API key with direct billing, and the tool returns raw responses per model. This goes beyond annotations without contradiction.

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

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

The description is a single coherent paragraph that front-loads the primary action and output, then details model options and return structure. It avoids fluff while covering all essentials. Slightly longer than ideal but efficient given the richness.

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 explicitly states the return format (per-model {score, confidence, signals, raw_response} + combined view). It also covers parameters, use cases, and behavioral notes. For a 4-parameter read-only tool, this provides sufficient completeness for an agent to use correctly.

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

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

Schema coverage is 100%, so all parameters are documented in the schema. The description adds practical nuance (default model, _apiKey usage, context purpose) that enhances the schema descriptions. It does not merely repeat but supplements meaningfully.

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 'probe' and the resource 'LLMs' for visibility scoring. It specifies the output (score 0-100, per-model results, combined view) and distinguishes its purpose from sibling tools like 'ask_pipeworx' and 'scan_competitor_ai_presence' by focusing on general brand/topic visibility across multiple models.

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

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

The description provides concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model and optional Anthropic integration with BYO key. It does not explicitly list when not to use it or compare directly with siblings, but the context is clear enough for an agent to decide.

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

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

Beyond annotations (readOnly, openWorld, idempotent, not destructive), description reveals routing to 3,745 tools, automatic argument filling, and structured citation output. Fully transparent about 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?

Well-structured with bold directive, clear list of sources, usage cues, and examples. Slightly long but each sentence adds value; could be slightly tighter.

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 purpose, usage, and return format (citations). Lacks mention of error handling or authentication, but given the complexity and annotation richness, it is sufficiently complete for an agent.

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

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

Schema already has 100% coverage with aliases described. Description adds minimal new info beyond examples. Parameter semantics are adequately clear from 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?

Description clearly states the tool routes questions to thousands of tools across verified sources for structured data, explicitly contrasting with web search. It lists numerous specific content domains, making the purpose unmistakable.

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

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

Provides explicit guidance to prefer over web search for factual questions and lists example query types. However, it does not differentiate from sibling tools like ask_pipeworx_grounded, which would further refine when to use this exact 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?

Describes key behaviors beyond annotations: hallucination-resistance, extraction from tool results only, extra LLM cost, and explicit refusal reasons. No contradiction with annotations; adds significant 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?

Decently concise, front-loads purpose and key behavior. Each sentence adds value, though a minor redundancy exists (aliases could be summarized more briefly).

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

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

Comprehensive for a complex tool with no output schema: explains return format, refusal reasons, and the extraction mechanism. Contextually complete given the tool's high-stakes nature.

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

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

Input schema has 100% coverage with descriptions for all aliases. Description does not add additional parameter meaning beyond what schema already provides, so baseline of 3 is appropriate.

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

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

Clearly states it is a hallucination-resistant answer mode for high-stakes reads. Distinguishes from sibling ask_pipeworx by explaining it extracts answers only from tool output, and highlights structured returns including refusal reasons.

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 use when answers will be quoted, cited, or acted upon and facts must not be invented. Also recommends preferring ask_pipeworx for casual lookups, providing clear when-to-use and when-not-to-use guidance.

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

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

The description is extremely detailed about behavior: fan-out logic, response shapes, resolver contract, parent event extractor, news fields, safety mechanisms (low-confidence short-circuits, closed market handling), and resolution-rule risk. This goes far beyond the annotations, which only indicate read-only and idempotent behavior.

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

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

The description is long but every section adds value. It is well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). However, it could be slightly more concise by reducing redundancy in the safety and resolution-rule paragraphs.

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

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

Given the tool's complexity (3 parameters, no output schema, but detailed annotations), the description covers all necessary scenarios: matching, low confidence, closed markets, wide spreads, resolution rules, and evidence handling. It leaves no significant gaps for an agent to misuse the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra context for each parameter: it explains depth values (quick vs thorough), market input types, and include_raw implications. This adds meaningful guidance beyond the schema descriptions.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data in one call. It specifies the verb 'research', the resource 'Polymarket bet', and explains the process. It distinguishes from siblings like polymarket_edges by being a comprehensive research 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 provides usage examples ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). It gives clear context for when to use the tool but does not explicitly state when not to use it or list 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, etc. The description adds valuable behavioral context: off-calendar fiscal years handled correctly, results sorted by primary metric, returns paired data with citation URIs, and replaces 8-15 sequential lookups. No contradictions with annotations.

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

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

The description is a single block of text but is front-loaded with examples and key instructions. It is relatively concise given the amount of information, though it could be slightly more structured (e.g., bullet points). 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?

The description is fairly complete: it explains the purpose, input, and output (paired data + citation URIs). However, without an output schema, the description could provide more detail on the exact structure of the returned data. It also could mention sibling tools like entity_profile for single-entity lookups, but it does reference the alternative (sequential lookups).

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

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

Schema coverage is 100% (both parameters with descriptions). The description adds meaning beyond schema by explaining what company type pulls (10-K revenue, net income, etc.) and drug type pulls (FAERS counts, FDA approvals). It also specifies input format (tickers/CIKs for company, drug names). However, schema already has enum and min/max, so the added value is moderate.

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 side-by-side comparison of 2-5 companies or drugs in one call, using verbs like 'compare' and 'rank'. It distinguishes from sequential lookups by explicitly saying 'ALWAYS PREFER over sequential single-pack lookups'.

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

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

It provides explicit usage examples ('which is bigger', 'rank these companies') and states when to use this tool ('ALWAYS PREFER'). It also describes what data is pulled for each type, giving clear context. No exclusions or alternatives to other sibling tools are mentioned, but the guidance is strong for its intended use.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which are consistent with the description. The description adds significant behavioral context: decomposition into sub-questions, parallel routing to 3,745 tools, grounded answers with evidence and confidence, handling gaps, and returning a structured findings packet. 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 relatively concise with multiple sentences, each adding value: purpose, mechanism, use cases, requirements, and timing. It is front-loaded with the core purpose. Slightly long but well-structured, earning a 4.

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

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

Given the tool's complexity and lack of output schema, the description covers almost everything an agent needs: what it does, how it works, what it returns (structured findings with evidence and gaps), when to use it, and prerequisites. Minor omission of exact output JSON structure prevents a 5.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the depth parameter values (quick=3, standard=5, thorough=8) and that the question can be broad/multi-part, going beyond the schema descriptions. It doesn't detail exact output format but adds 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 performs 'grounded multi-source research in ONE call' and distinguishes it from sibling tools like ask_pipeworx, which is for single lookups. It specifies the verb (research) and resource (multi-source), making the purpose unambiguous.

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

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

The description explicitly says when to use this tool ('broad or multi-part questions') and when not to ('use ask_pipeworx for single lookups'). It also mentions prerequisites (Pipeworx account, paid plan for thorough depth) and expected time (15-60s), providing comprehensive 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 adds that it returns top-N tools with schemas and examples, ready to call. Annotations already indicate readOnly and idempotent, but description clarifies output structure and no-destructive 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?

Concise 80-word description. Front-loaded with purpose, lists domains, output details, and usage advice. No wasted sentences.

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

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

Comprehensive for a discovery tool. Covers input, output format, and usage strategy. Lacks pagination details but not critical.

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

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

Schema has 100% coverage. Description mentions 'top-N' and limit range but repeats schema info. No additional parameter meaning beyond schema.

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

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

Description clearly states the tool finds tools by describing data/task. Provides specific domain list and emphasizes calling first. Distinguishes from sibling tools which are specific tasks.

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' and 'call this FIRST when you have many tools'. Gives context but lacks explicit when-not-to-use.

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

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

Beyond the annotations (readOnlyHint=true, etc.), the description details the sources fanned out (SEC, XBRL, USPTO, news, GLEIF), the specific data returned (cik, filings with URIs, fundamentals sorted, patents soft-fails, news fallback), and the deprecation note for USPTO API. 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 a single dense paragraph that is informative but somewhat verbose. It front-loads the purpose with example queries but then packs many details. Could be more concise or structured for easier skimming. It earns its place but could be improved.

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 (multiple sources, fallbacks, deprecation) and no output schema, the description covers the key behavioral aspects: what data is returned, ordering, fallbacks, and limitations. It doesn't specify exact response format but provides enough context for an agent to understand the tool's capabilities.

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 has 100% coverage with descriptions for both parameters. The description adds context about why type is restricted to 'company' and why names are not supported, reinforcing the schema and providing guidance beyond the schema. However, it does not add significant new meaning beyond clarification.

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 provides a 'full cross-source profile of a US public company in ONE parallel call'. It lists example queries and explicitly distinguishes from sibling tools like `resolve_entity` by noting names are not supported. The purpose is specific and unambiguous.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also provides clear input guidance: ticker or CIK, and directs to use `resolve_entity` first for names. This gives complete when-to-use and when-not-to-use guidance.

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

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

Description says 'Delete', which aligns with annotations (destructiveHint=true). No contradictions. Does not add additional behavioral details beyond annotations, which already convey destructiveness.

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. First sentence states action, second provides usage guidance. No unnecessary words.

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

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

Simple tool with one parameter and no output schema. Description covers purpose and usage sufficiently. No gaps given the tool's simplicity.

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

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

Schema covers 100% of parameters with a clear description for 'key'. Description does not add extra meaning beyond what the schema provides, so baseline 3.

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

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

Description clearly states verb 'Delete', resource 'previously stored memory', and identifies the key as the identifier. Distinguishes from siblings (remember, recall) by indicating it's for 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?

Explicitly states when to use: when context is stale, task done, or clearing sensitive data. Also suggests pairing with remember and recall, providing context for alternatives.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details (fetches page, extracts title/description/key links, emits standard format) and output format, though no mention of rate limits 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?

The description is two sentences plus a bullet list of use cases. It is front-loaded with the main purpose, and every sentence adds value without redundancy.

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

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

For a simple read-only tool with 2 parameters and no output schema, the description covers purpose, behavior, output format, and use cases. Lacks error handling details but sufficient for most agents.

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% as both parameters are described in schema. The description adds minimal value: an example for 'url' and no extra for 'max_links'. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a 'production-ready llms.txt file for any URL'. It specifies the verb (generate), resource (llms.txt), and context (AI crawlers), and the use cases differentiate it from siblings.

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

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

The description explicitly lists use cases (client's site, own project, auditing competitor), providing clear context for when to use. However, it omits when not to use or alternatives.

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

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

Discloses return fields and default behavior (active only). Annotations already declare readOnlyHint, idempotentHint, destructiveHint; description adds meaningful context beyond that.

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, no redundancy. First sentence states purpose and return fields, second gives usage guidance.

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, description specifies return fields. Single parameter fully documented. Behavior is clear and complete.

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

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

Schema already covers 100% of parameter descriptions. The single parameter (include_inactive) is simple boolean; description adds no extra meaning.

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

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

Specific verb 'List' with resource 'subscriptions'. Clearly distinguishes from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Explicitly states when to use: review monitoring before adding more or find an id to cancel. Implicitly guides away from use for modification.

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 discloses rate limit (5 per identifier per day), free usage, and no quota impact, which go beyond annotations. Annotations show write but not destructive; description clarifies it's a feedback send. Team reading frequency is mentioned.

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

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

Four sentences, each serving a clear purpose: purpose, use cases, best practices, and rate/cost information. No redundancy or fluff. Front-loaded with the core action.

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

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

Given the tool's simple nature (sending feedback), the description covers what each type means, how to structure the message, rate limits, and cost. No output schema needed. No gaps identified.

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 parameters. The description adds context for the 'type' enum values and advises on message specificity (include tool name, error, etc.) and length. Adds value beyond schema.

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

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

Description clearly states the tool's purpose: to send feedback (bug, feature, data_gap, praise) to the Pipeworx team. It distinguishes from siblings like ask_pipeworx and discover_tools by focusing on feedback rather than inquiry or exploration.

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

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

Explicit when-to-use scenarios are provided (bug, feature/data_gap, praise) along with a concrete prohibition (don't paste end-user prompt). Rate limiting and quota info are given. Missing explicit when-not-to-use or alternatives, but siblings are sufficiently different so not critical.

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?

Describes data source (CF analytics-engine), no PII, and caching behavior (5min-1h). Annotations already declare readOnly and idempotent, so description adds valuable context beyond that.

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 and well-structured, with main purpose first, then use cases, then data details. Every sentence is informative, though could be slightly tighter.

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

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

The description covers all relevant aspects: what is returned, windows, use cases, data source, privacy, caching. With no output schema and simple input, it is fully complete.

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

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

Schema coverage is 100% for the single parameter 'window'. The description adds useful context about shorter vs longer windows, enhancing 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?

The description clearly states the tool returns top tools, packs, and call volume over recent windows. It uses specific verbs and resource, and the tool is distinct from siblings like discover_tools.

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

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

Provides three explicit use cases for when to use the tool, but does not mention when not to use it or compare directly to siblings. Still, the context 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?

Annotations already declare readOnly, idempotent, openWorld. Description adds rich internal logic: monotonicity checks, partition sum, semantic anchor, partition filter, fill check with order book depth. No contradiction.

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

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

Description is detailed but well-organized with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value; could be slightly tightened but appropriate for complexity.

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

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

Despite no output schema, description fully explains response structure (opportunities array with fields, partition_check object in event mode, fill check details). Refers to polymarket_fill_risk for custom sizing. Complete for intended use.

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

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

Schema coverage is 100%, but description adds significant meaning: explains that event mode walks child markets and computes partition_check, topic mode searches related events and applies Jaccard similarity. Goes well beyond schema descriptions.

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

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

Description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, with two distinct modes (event and topic). Distinguishes from siblings like polymarket_edges or polymarket_fill_risk.

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

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

Explicitly requires one of event or topic, warns against no args. Recommends event for specific markets, topic for cross-event scanning. Mentions prerequisites like Jaccard similarity and placeholder filter. Provides clear when-to-use guidance.

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

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

The description is highly transparent, detailing the three model families, edge calculation, output segments, diagnostics, and caching behavior ('Cached 1h at the KV level'). It adds significant value beyond annotations, which already declare readOnlyHint=true and idempotentHint=true.

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

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

The description is dense but well-structured with clear sections (models, output, knobs). It front-loads the purpose. While long, it uses each sentence efficiently given the complexity of the tool (9 parameters, 3 segments). Minor excess could be trimmed, but overall appropriate.

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 thoroughly explains the response structure (segments, diagnostics, field meanings) and how parameters affect results. It covers caching, edge calculation, and filter rationale, making it self-contained.

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

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

Schema coverage is 100%, and the description adds rich context beyond schema. For example, 'min_kelly' is explained as 'Skips opportunities that are too small to bet sensibly,' and 'min_partition_leg_kelly' clarifies its application to partition legs. Each parameter gets qualitative explanation of its effect.

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

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

The description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' with a specific verb and resource. It also distinguishes from sibling tools like polymarket_arbitrage and polymarket_fill_risk by focusing on edge discovery.

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

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

The description includes explicit usage guidance: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also notes that Fed bets are excluded from ranking and explains knob filters. However, it does not explicitly mention when not to use this tool compared to 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 declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, indicating a safe read operation. The description adds substantial behavioral context: it uses daily snapshots, provides time-series, computes trend classification and decay rate, explains expiration handling, and details data gaps due to snapshot TTL. No contradictions with annotations.

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

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

The description is somewhat verbose and could be more concise. However, it is well-structured with clear sections (RESPONSE and LIMITS) and front-loads the key question. Every sentence adds value, but some details could be shortened without losing meaning.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and key fields. It covers data freshness, limitations (60-day TTL, snapshot gaps), and caveats about decay computation. This is highly complete for a tool of this complexity.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description adds value by clarifying defaults (days=14, window='1wk'), max lookback (30), and explaining the meaning of 'window' as a snapshot family. It also mentions snapshot gaps, but this is more about behavior than parameter semantics.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. It uses specific verbs like 'track' and 'analyze' and distinguishes from siblings like polymarket_edges by focusing on historical trends rather than current 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 explains when to use the tool (to understand edge history and decay) and provides context about trading implications ('a fresh wide edge and a 3-week-old wide edge are different trades'). However, it lacks explicit instructions on when not to use it or direct comparisons with alternative tools, though sibling tools imply alternatives exist.

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

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

Annotations already mark it as read-only, open-world, idempotent, non-destructive. The description adds rich behavioral details: walks the ladder, returns verdicts (clean|degraded|cannot_fill), covers basket-specific per-leg fill details, thin legs, and forced directional risk. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections (general, single-market, basket, usage guideline). It is front-loaded with the essential function. While every sentence is informative, it could be slightly more concise without losing clarity, but given the complexity, it is justified.

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

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

No output schema, so the description must cover return values. It does comprehensively: single-market returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; basket returns theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk. All necessary behavioral context is provided.

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

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

Schema coverage is 100% with descriptions, but the description adds critical context: explains size_usd interpretation differs between single-market and basket, default auto-detection of side for basket, clamp range 10–1,000,000. Adds significant meaning beyond schema.

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

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

The description clearly states it performs a realizable-vs-theoretical edge check against live CLOB order-book depth, distinguishing between single-market and basket modes. It also ties into sibling tools like polymarket_arbitrage and polymarket_edges, making the purpose distinct.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and explains why (theoretical overround uncapturable, partial fills lead to unhedged directional positions). Provides clear when-to-use and rationale.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond by explaining compatibility_warning triggers (matched_pairs:0 with skipped_cross_type>0 or both venues >5 legs), temporal_alignment, and skipped_cross_type/cross_subtype counters. 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 fairly long but well-structured. It front-loads the core purpose and modes, then details safety fields and counters. Each sentence adds value, though some repetitive phrasing (e.g., 'compatibility_warning fires in two cases') could be tightened. Still, it is effective for a complex tool.

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

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

Given no output schema, the description comprehensively explains the response structure: leg-by-leg prices, matched spread (top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters). It covers edge cases and potential pitfalls, providing a complete picture for the agent.

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

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

Schema coverage is 100% with good descriptions for each parameter. The description adds context: topic lists the 10 shortcuts (fed, btc, etc.) and explains that explicit overrides the topic-mapped side. It clarifies that topic auto-fetches matching events, which goes beyond the schema's 'Pre-mapped' and 'Explicit' phrasing.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly identifies the specific verb (calculate spread) and resource (cross-venue pairs). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparison rather than intra-venue 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?

Two modes are explicitly described: topic for pre-mapped shortcuts and explicit for custom pairings. The description warns that most pre-mapped topics return compatibility_warning, so pre-mapped ≠ tradeable. It also specifies when spreads are meaningful (equivalent bet shapes, temporal alignment) and when they are not (compatibility_warning conditions).

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. The description adds value by disclosing scoping (anonymous IP, key hash, account ID) and pairing with remember/forget. No contradictions.

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

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

The description is two concise sentences that front-load the action and provide necessary context. Every word serves a purpose, with no redundancy.

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

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

The description explains behavior with and without the key, scoping, and relationship to siblings. No output schema exists, but for a simple retrieval tool, the description covers essential aspects 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?

The single parameter 'key' is fully covered by the schema description (100%). The description adds minimal extra meaning beyond 'omit to list all keys', which is already implied by the schema's optionality.

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

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

The description clearly states the tool's action: retrieve a saved value or list keys. It includes specific examples like 'user's target ticker' and distinguishes from siblings (remember, forget) implicitly.

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

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

It describes when to use the tool (look up stored context) and provides concrete use cases (ticker, address, notes). It mentions scoping but doesn't explicitly state when not to use it or alternatives, though the context is clear.

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

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

Annotation contradiction: readOnlyHint=true but description includes mark_read:true which writes (flags events read). The description discloses the behavior, but this contradicts the annotation, scoring 1 per rules.

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, efficient and front-loaded with main action. No redundancy, every sentence adds value including the alternative HTTP endpoint note.

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 return fields, filtering, mark_read behavior, and alternative access. Missing pagination details but limit parameter is in schema. Adequately complete for a read-only feed tool.

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

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

Schema coverage is 100% (baseline 3). Description adds value by explaining mark_read effect (flags read for next call) and giving filter examples (e.g., 'sec_8k'), going 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?

Clearly states it pulls fired events from subscription feed and returns recent alerts with specific fields like source and citation_uri. Differentiates from sibling tools like list_subscriptions which list subscriptions, not alerts.

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

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

Gives context like 'polls work fine' and mentions alternative access via HTTP endpoint, implying use for interactive queries. No explicit when-not-to-use, but it's clear for its purpose.

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 multi-source fan-out, rate-limiting fallback, API sunset, and response structure (changes grouped, total count, citation URIs). 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?

Single dense paragraph but front-loaded with purpose and examples. Every sentence adds value. Could be more structured but appropriate length for the information conveyed.

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

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

Given no output schema, the description explains return structure and includes all necessary context: parameters, behavior, alternatives, and limitations. Fully sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by explaining the 'since' parameter with examples (ISO date, relative shorthand), 'value' as ticker/CIK, and 'type' limitation to 'company'. Slightly above baseline.

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

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

The description clearly states the tool provides a change feed for a company in a time window, listing example queries and specific data sources. It distinguishes itself from sibling tool entity_profile by contrasting use cases.

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

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

Explicitly states when to use (change feed queries) and when not (use entity_profile for static profile). Provides examples and parameter guidance, including fallback behavior for GDELT→GNews and USPTO soft-failure.

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 idempotentHint=true (suggesting overwrite), readOnlyHint=false, and destructiveHint=false. The description adds valuable context: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. It does not contradict annotations and provides sufficient behavioral insight beyond them.

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

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

The description is concise, consisting of exactly two sentences that are front-loaded with the core purpose. Every sentence adds necessary context, with no redundant or filler content.

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

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

Given the tool has only two required parameters, no output schema, and good annotations, the description covers all necessary context: when to use, how scoping works, persistence behavior, and pairing with sibling tools. It is fully complete for an agent to understand and invoke correctly.

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

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

Schema description coverage is 100%, with both key and value having detailed descriptions including examples. The tool description reinforces this context by explaining the purpose of the key-value pairs, but it adds little new semantic information beyond what the schema already provides.

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

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

The description starts with a clear verb ('Save') and resource ('data'), specifying that it is for reuse across conversations or sessions. It distinguishes itself from sibling tools recall and forget by explicitly pairing with them, giving agents a clear understanding of the tool's purpose.

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

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

The description provides explicit guidance on when to use the tool: 'when you discover something worth carrying forward'. It also mentions replacements (e.g., 'resolved ticker, target address, user preference, research subject') and references sibling tools recall and forget, setting clear context for usage.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds transparency about internal cascading ('cascades through several lookup endpoints internally') and specifies return fields (ticker, CIK, RxCUI, citation URIs). This goes beyond annotation hints.

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

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

The description is well-structured with examples and explicit usage instructions. It is fairly concise but could be slightly tighter by merging some repetitive phrases. Nevertheless, every sentence contributes to understanding.

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 (two entity types, multiple return fields, citation URIs, internal cascading), the description provides sufficient detail on what it does and returns. It lacks error handling or output schema, but the description compensates with return value specifics.

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

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

Schema coverage is 100%, so description is not required but adds value with examples (e.g., 'AAPL', '0000320193', 'ozempic') and notes auto-disambiguation for company inputs. This enhances 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 uses specific verbs ('resolve', 'look up') and clearly states the resource (entity names to canonical IDs). It lists example queries and supported types (company, drug). It distinguishes itself from siblings by explicitly saying 'Use FIRST whenever you have a name but need an ID.'

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

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

The description provides clear guidance on when to use the tool ('when you have a name but need an ID') and mentions that it replaces multiple manual lookups. However, it does not explicitly state when not to use it or discuss alternatives among 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, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks results, and returns a ranked list with score, confidence, signal density. This enriches understanding beyond annotations.

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

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

The description is concise (around 100 words) and well-structured: it starts with the main action, then explains the method, gives a use case, and describes the output. 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?

Despite having no output schema, the description explicitly states the return format: 'ranked list with score, confidence, signal density per entity.' It also covers all parameters and usage context. For a tool with rich annotations and full parameter coverage, this is complete.

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

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

Schema coverage is 100%, but the description adds crucial semantics: 'First entry treated as the subject for narrative; rest are competitors.' It also clarifies that _apiKey is only needed if 'anthropic' is in models. This adds meaning beyond what the schema provides.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (compare), resource (AI visibility of entities), and scope (multiple). It distinguishes itself from the sibling tool 'ai_visibility_check' which is for single entities.

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

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

The description provides a concrete use case: 'Useful for competitive AI-marketing audits: does Claude know about us as well as our competitors?' It implies when to use (comparing multiple entities) versus using ai_visibility_check for single entities. However, it does not explicitly state when not to use or mention alternative 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 cover safety (readOnly, idempotent, nondestructive). The description adds critical behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list it if it times out. It also describes the return structure (summary block, per-advisory detail, links, alternative versions).

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 long but well-structured and information-dense. Every sentence adds value. Front-loaded with the main purpose. Could be trimmed slightly, but overall efficient.

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

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

Given the complexity (multiple sources, partial failures, no output schema), the description is remarkably complete. It explains the composite behavior, fallback handling, output fields, and limitations like bundlephobia delays. It provides sufficient information for an AI agent to understand what the tool returns and its edge cases.

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

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

Schema description coverage is 100% (both parameters described). The description adds only minor context: mentions scoped packages and version default, but the schema already provides these details. Baseline of 3 is appropriate as the description does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool performs a composite 'should I add this npm package' check, combining multiple data sources (deps.dev, bundlephobia). It uses specific verbs like 'check', 'fans out', 'Returns' and distinguishes from siblings by noting NPM ecosystem only in v1 and that other ecosystems go via deps.dev:version directly.

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: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides when-not-to-use: NPM ecosystem only, and for other ecosystems use deps.dev:version directly. This provides 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, and non-destructive. The description adds significant detail: uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, a hard cap of 200K chars with truncation flagging, and returns per-passage offsets for verification. 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 efficiently structured with a clear first sentence stating the core function, followed by usage rationale and technical details. Every sentence adds value without redundancy.

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

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

Without an output schema, the description thoroughly explains what the tool returns: top-N passages with character offsets and similarity scores. It also covers limits (200K chars, truncation) and provides usage context. For a 3-parameter tool, this is fully complete.

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

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

Schema description coverage is 100%, but the description adds meaningful context beyond the schema: it explains the underlying retrieval mechanism (embeddings, windows, scoring), notes the character limit for 'text', and gives example queries for 'query'. This helps the agent understand how to effectively use the parameters.

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: 'Semantic search INSIDE a fetched record.' It specifies the action (semantic search), the resource (a record's text), and the output (top-N passages with offsets and scores). It distinguishes from siblings by noting the pairing with ask_pipeworx_grounded.

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

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

The description provides explicit guidance on when to use: 'Use when the record is too big to cram into the prompt.' It also explains how it pairs with another tool. However, it does not explicitly state when not to use or mention alternatives among the 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 indicate safe, read-only, idempotent behavior. The description further discloses the fixed outcome ('always no'), the rotating reason, risk level ('catastrophic'), suggested day, and on-call sympathy score, adding rich behavioral context beyond annotations.

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

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

The description is two sentences long, direct, and front-loaded with the core purpose. Every sentence adds value with no redundancy or fluff.

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

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

Given the tool's simplicity (no required params, full schema coverage, and existing output schema), the description is complete. It covers the fixed outcome, return fields, and humorous nature without 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 all three parameters fully described. The description does not add additional meaning or usage context for the parameters beyond what the schema provides.

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

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

The description clearly states the tool checks whether to ship on Friday with a specific verb and resource ('ship_on_friday_check'). The humorous twist ('The answer is always no') adds clarity and distinguishes it from sibling tools which are unrelated.

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 implicitly tells when to use (when considering Friday shipping) but does not explicitly state when not to use or provide alternatives. Given the tool's specificity, this is adequate.

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

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

Annotations indicate idempotentHint=true but the description doesn't clarify idempotency behavior (e.g., duplicate subscription handling). However, it provides rich behavioral details: authentication needs, SMS cap (10/day), webhook auto-disable after 10 failures, and that the webhook secret is returned once. These go beyond annotations, though the idempotency gap prevents a 5.

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

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

The description is dense but well-structured: purpose, requirements, types with examples, delivery options. Every sentence adds value. Could be slightly more compact, but it's clear and front-loaded, making it easy for an agent to parse.

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

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

Given no output schema, the description mentions the return value (new subscription id), which is sufficient. It covers requirements, types, and delivery. It assumes knowledge of sibling tools for retrieval (recent_alerts) and management (list_subscriptions, unsubscribe), but that's reasonable. Missing a note on how the always-on feed is consumed, but recent_alerts handles that.

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 extensive examples for each subscription type's params, including optional vs required constraints (e.g., clinical_trial requires sponsor or condition). Delivery channel details go far beyond the schema, explaining rate limits and webhook mechanics. This full parametric explanation enables precise invocation.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream, returns the new subscription id, and distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation. It provides specific examples of supported types, making the purpose unambiguous.

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

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

The description specifies requirements (Pipeworx OAuth account, anonymous/BYO cannot persist subscriptions), details each subscription type with use-case examples, and explains delivery channels. While it doesn't explicitly state when not to use this tool vs alternatives, the context is clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by explaining the output format (category-bucketed examples with exact tool+argument shapes) and that it draws from a live catalog. 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 front-loaded with common user questions and is comprehensive, but slightly long. Each sentence adds value, but it could be trimmed without losing essential 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 simplicity (one optional parameter, no output schema), the description is complete: it explains when to use, what it returns, how to call it, and provides examples of topics and categories.

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

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

Schema coverage is 100% with a clear description for the 'topic' parameter. The description adds example values and clarifies that omitting gives a cross-category spread, enhancing understanding beyond the schema.

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

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

The description clearly states the tool's purpose: it returns category-bucketed example questions with specific tool+argument shapes, serving as an onboarding entry point. This distinguishes it from siblings like ask_pipeworx, entity_profile, etc.

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

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

Explicitly specifies when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. Also provides guidance on argument usage: call with no arguments for full spread or pass a topic to focus. Implicitly contrasts with other meta-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?

The description adds significant behavioral context beyond annotations: ownership enforcement, deactivation vs deletion, and preservation of historical events. This complements the annotations (readOnlyHint=false, destructiveHint=false) without contradiction.

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

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

Two concise sentences with zero waste. Every sentence adds value, and the structure is front-loaded with the purpose.

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

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

For a tool with one required parameter and no output schema, the description is fully sufficient. It covers purpose, constraints, and side effects.

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

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

Schema description coverage is 100% for the single parameter. The description mentions 'by id' but does not add meaning beyond the schema's description of the 'id' field. Baseline of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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

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

The description provides clear context on when to use ('ownership is enforced — you can only cancel your own subscriptions') and what the effect is ('deactivated, not deleted'). It implies when not to use (if you don't own the subscription). It does not explicitly compare with alternatives but is adequate given sibling context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds context about data sources (SEC EDGAR + XBRL), return types (verdicts, values, citations), and efficiency gains. No contradictions.

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

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

The description is somewhat long but front-loaded with example intents. It efficiently packs all relevant information without redundancy. Could be slightly more concise, but structure is clear.

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 a single simple parameter, extensive annotations, and no output schema, the description fully covers the tool's behavior, scope, and return values. It also explains the benefit (replacing multiple calls).

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, 'claim', is described in the schema with examples. Schema coverage is 100%. The tool description does not add new meaning beyond the schema; it repeats examples. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides examples of user intents and specifies the domain (company-financial claims for public US companies). It is distinct from siblings, none of which are claim verification tools.

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

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

The description advises to use whenever the agent needs to check factual correctness of a user's statement. It mentions the scope of supported claims and what the tool replaces (4-6 sequential calls). It does not explicitly state when not to use it, but the scope limitation is clear.

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